HubSpot MCP 服务器

概述

这是一个模型上下文协议（MCP）服务器实现，提供了与 HubSpot CRM 的集成。该服务器通过标准化接口使 AI 模型能够与 HubSpot 数据和操作进行交互。

有关模型上下文协议及其工作原理的更多信息，请参阅 Anthropic 的 MCP 文档。

组件

资源

服务器公开了以下资源：

• hubspot://hubspot_contacts：一个动态资源，提供对 HubSpot 联系人的访问
• hubspot://hubspot_companies：一个动态资源，提供对 HubSpot 公司的访问
• hubspot://hubspot_recent_engagements：一个动态资源，提供对过去 3 天内 HubSpot 互动的访问

所有资源都会随着其各自对象在 HubSpot 中的修改而自动更新。

示例提示

• 从 LinkedIn 个人资料网页复制创建 HubSpot 联系人：

  根据以下信息创建 HubSpot 联系人和公司：

  John Doe
  Tech Corp 的软件工程师
  旧金山湾区 • 500+ 连接

  工作经历
  Tech Corp
  软件工程师
  2020 年 1 月 - 至今 · 4 年
  加利福尼亚州旧金山

  前公司 Inc.
  高级开发人员
  2018 - 2020 · 2 年

  教育背景
  加利福尼亚大学伯克利分校
  计算机科学学士
  2014 - 2018

• 获取您公司的最新活动：

  我的业务流程最近有什么新动态？

工具

服务器提供了多种工具来管理 HubSpot 对象：

联系人管理工具

• hubspot_get_contacts

  • 从 HubSpot 检索联系人
  • 不需要输入
  • 返回：联系人对象数组

• hubspot_create_contact

  • 在 HubSpot 中创建新的联系人（创建前检查重复项）
  • 输入：
    • firstname (字符串)：联系人的名字
    • lastname (字符串)：联系人的姓氏
    • email (字符串, 可选)：联系人的电子邮件地址
    • properties (字典, 可选)：额外的联系人属性
      • 示例：{"phone": "123456789", "company": "HubSpot"}
  • 行为：
    • 检查是否存在具有相同名字和姓氏的现有联系人
    • 如果在属性中提供了 company，还会检查具有相同公司的匹配项
    • 如果找到匹配项，则返回现有联系人的详细信息
    • 仅当未找到匹配项时才创建新联系人

公司管理工具

• hubspot_get_companies

  • 从 HubSpot 检索公司
  • 不需要输入
  • 返回：公司对象数组

• hubspot_create_company

  • 在 HubSpot 中创建新公司（创建前检查重复项）
  • 输入：
    • name (字符串)：公司名称
    • properties (字典, 可选)：额外的公司属性
      • 示例：{"domain": "example.com", "industry": "Technology"}
  • 行为：
    • 检查是否存在具有相同名称的现有公司
    • 如果找到匹配项，则返回现有公司的详细信息
    • 仅当未找到匹配项时才创建新公司

• hubspot_get_company_activity

  • 获取特定公司的活动历史记录
  • 输入：
    • company_id (字符串)：HubSpot 公司 ID
  • 返回：活动对象数组

互动工具

• hubspot_get_recent_engagements
  • 获取过去 3 天内来自所有公司和联系人的 HubSpot 互动
  • 不需要输入
  • 返回：带有完整元数据的互动对象数组

多用户支持这台MCP服务器设计用于与多个HubSpot用户协同工作，每个用户都有自己的访问令牌。该服务器不使用全局环境变量来存储访问令牌。

相反，对MCP服务器的每次请求都应通过以下任一方式包含用户的特定访问令牌：

1. 在请求头中：X-HubSpot-Access-Token: your-token-here
2. 在请求体中作为accessToken：{"accessToken": "your-token-here"}
3. 在请求体中作为hubspotAccessToken：{"hubspotAccessToken": "your-token-here"}

这种设计允许您在自己的后端（例如Supabase）中存储用户令牌，并随每次请求一起传递。

多用户集成示例

javascript
// 示例展示了如何在多用户设置中使用此MCP服务器
async function makeHubSpotRequest(userId, action, params) {
// 从数据库检索用户的HubSpot令牌
const userToken = await getUserHubSpotToken(userId);

// 使用用户的令牌向MCP服务器发出请求
const response = await fetch('https://your-mcp-server.vercel.app/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-HubSpot-Access-Token': userToken
},
body: JSON.stringify({
action,
...params
})
});

return await response.json();
}

设置

前提条件

您需要为每个用户提供一个HubSpot访问令牌。您可以按照以下步骤获取：

1. 在您的HubSpot账户中创建一个私有应用：
   • 遵循HubSpot私有应用指南

     • 转到您的HubSpot账户设置

     • 导航至集成 > 私有应用

     • 点击“创建私有应用”

     • 填写基本信息：

       • 应用名称
       • 添加描述
       • 上传徽标（可选）

     • 定义所需权限范围：

       • oauth（必需）

     • 可选权限范围：

       • crm.dealsplits.read_write
       • crm.objects.companies.read
       • crm.objects.companies.write
       • crm.objects.contacts.read
       • crm.objects.contacts.write
       • crm.objects.deals.read

     • 审核并创建应用

     • 复制生成的访问令牌

注意：请确保您的访问令牌安全，切勿将其提交到版本控制系统中。

Docker安装

您可以选择本地构建镜像或从Docker Hub拉取。该镜像是为Linux平台构建的。

支持的平台

• Linux/amd64
• Linux/arm64
• Linux/arm/v7

选项1：从Docker Hub拉取

bash
docker pull buryhuang/mcp-hubspot:latest

选项2：本地构建

bash
docker build -t mcp-hubspot .

运行容器：
bash
docker run
buryhuang/mcp-hubspot:latest

跨平台发布

要为多个平台发布Docker镜像，可以使用docker buildx命令。请遵循以下步骤：

1. 创建一个新的构建器实例（如果您还没有的话）：
   bash
   docker buildx create --use

2. 为多个平台构建并推送镜像：
   bash
   docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-hubspot:latest --push .

3. 验证指定平台上的镜像是否可用：
   bash
   docker buildx imagetools inspect buryhuang/mcp-hubspot:latest

与Claude Desktop配合使用

通过Smithery安装

要通过Smithery自动为Claude Desktop安装mcp-hubspot，请执行以下命令：
bash
npx -y @smithery/cli@latest install mcp-hubspot --client claude

Docker使用

json
{
"mcpServers": {
"hubspot": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"buryhuang/mcp-hubspot:latest"
]
}
}
}

开发

要设置开发环境，请执行：
bash
pip install -e .

许可证

本项目根据MIT许可证授权。