MCP 服务器

HubSpot MCP Server

一个服务器，它使人工智能模型能够通过标准化接口与 HubSpot CRM 数据和操作进行交互，支持联系人和公司管理，并具有基于令牌的多用户身份验证。

README

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 年
加利福尼亚州旧金山

Previous Company 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 服务器的每个请求都应通过以下方式之一包含用户的特定访问令牌：

在请求标头中：X-HubSpot-Access-Token: your-token-here
在请求正文中作为 accessToken：{"accessToken": "your-token-here"}
在请求正文中作为 hubspotAccessToken：{"hubspotAccessToken": "your-token-here"}

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

多用户集成示例

// 如何在多用户设置中使用此 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 访问令牌。您可以通过以下方式获得：

在您的 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 拉取

docker pull buryhuang/mcp-hubspot:latest

选项 2：在本地构建

docker build -t mcp-hubspot .

运行容器：

docker run \
  buryhuang/mcp-hubspot:latest

跨平台发布

要为多个平台发布 Docker 镜像，您可以使用 docker buildx 命令。请按照以下步骤操作：

创建一个新的构建器实例（如果尚未创建）：
```
docker buildx create --use
```

为多个平台构建和推送镜像：

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-hubspot:latest --push .

验证镜像是否可用于指定的平台：

docker buildx imagetools inspect buryhuang/mcp-hubspot:latest

与 Claude Desktop 一起使用

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 mcp-hubspot：

npx -y @smithery/cli@latest install mcp-hubspot --client claude

Docker 用法

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