Hubspot-MCP

# ohneben's HubSpot MCP [](https://github.com/ohneben/Hubspot-MCP/actions/workflows/ci.yml) [](https://github.com/ohneben/Hubspot-MCP/actions/workflows/docker-publish.yml) [](./LICENSE.md) **最完整的HubSpot MCP服务器**. 从 **Claude**、**Cursor** 或任何其他 [MCP](https://modelcontextprotocol.io) 客户端以纯语言运行您的整个 [HubSpot](https://www.hubspot.com/) 账户。 此 [Model Context Protocol](https://modelcontextprotocol.io) 服务器公开了**整个公共HubSpot API —— 1,076个端点工具，涵盖102个API** —— CRM、CMS、营销、自动化、对话、商务、文件、设置、Webhook等，均直接从HubSpot自己的OpenAPI定义中生成。每个工具都经过**安全分类**（🟢 只读 / 🟡 写入 / 🔴 破坏性），并且 —— 独特于此服务器 —— **Hub & Plan感知**：HubSpot发布了每个API需要的Hub和层级（免费 / 入门级 / 专业级 / 企业级），而此服务器直接将这些信息带入每个工具，并附带一个**实时能力报告**，适用于您的门户。它通过 **stdio**（Claude Desktop和其他本地启动器）或 **Streamable HTTP**（在Docker中托管）运行，并配备重试、客户端速率限制（调谐至HubSpot的突发上限）以及请求超时，以确保它能应对实时账户。 ## 为什么您需要它 一些MCP服务器只转发API的一小部分。而这一个是构建为**安全地交给LLM**、**完整**、**易于实际运行**的： | 您获得的功能 | 原因 | | --- | --- | | **1,076种工具 —— 整个公共API** | 联系人、公司、交易、票据、每种参与类型、关联v4、属性、管道、列表、导入/导出、营销电子邮件和活动、活动、表单、交易电子邮件、序列、工作流/动作、对话和自定义渠道、CMS页面/帖子/HubDB/源代码、文件、商务（发票、订单、购物车、付款、订阅）、设置、Webhook —— 没有手动挑选或遗漏的内容。大多数服务器只支持约30种CRM工具。 | | **Hub & Plan感知**（其他服务器都没有此功能） | HubSpot根据Hub和层级限制API —— HubDB需要**专业级**的内容/营销Hub，自定义对象模式需要**企业级**，序列需要**专业级**的销售/服务Hub。每个工具都说明了其需求，直接来自HubSpot自己的API索引。 | | **`hubspot_get_capabilities`** | 一个调用报告您的门户、您的令牌授予的范围、今日API使用情况与每日上限，以及每个工具组您的令牌实际解锁了多少端点，需要解锁其余端点的范围。可选的实时探测验证端到端访问。 | | **精选的安全类别** 🟢 / 🟡 / 🔴 | 不是天真的“GET = 安全”：`POST …/search`是一个**只读查询**，`merge`被标记为**不可逆**，`gdpr-delete`是一个**永久清除**（而非归档 → 回收站），列表成员调用是可逆的**链接**，`POST /crm/v3/imports`是一个**批量导入**，而交易电子邮件是**发送消息**。 | | **机器可读的MCP注释**（`readOnlyHint`，`destructiveHint`） | 尊重注释的主机（包括Claude）可以自动信任读取并在破坏性操作前要求确认。 | | **可行的错误提示** | 403并带有`MISSING_SCOPES` → 恰好需要添加的范围及其位置；一个被限制的API的纯403 → 需要的层级；401 → 令牌类型和到期指南；429 → 您的限制。模型获得的是**如何修复**，而不仅仅是**哪里出了问题**。 | | **只读模式和分组过滤** | 仅暴露443个🟢只读工具（`HUBSPOT_READ_ONLY=true`），或缩小到您使用的组（`HUBSPOT_INCLUDE_GROUPS=contacts,deals,cms:*`）。区域通配符包含在内。 | | **发现模式** | `HUBSPOT_TOOL_MODE=discovery`将1,000+工具列表替换为3个元工具（搜索/检查/调用同一个注册表）—— 相同的覆盖范围，上下文占用极小，并且只读模式仍然适用。 | | **真正的上传文件** | 多部分端点（文件、CRM导入、HubDB导入、CMS源代码）实际上有效 —— 内联传递文件内容或base64编码。 | | **自动重试和回退** | 瞬态`429`/`5xx`响应会重试并带有抖动的指数回退，遵守HubSpot的`Retry-After`头部。 | | **内置速率限制** | 在HubSpot的突发上限（默认100请求/10秒）下自我限制，并为`/search`端点配备**单独的限制器**（~5请求/秒）。工具调用的突发不会触发`429`。 | | **响应大小保护** | 可选地限制巨大的列表响应（`HUBSPOT_MAX_RESPONSE_CHARS`），以便一次调用不会超出模型的上下文窗口。 | | **CRM GraphQL直通** | HubSpot的GraphQL端点仅支持查询，因此这里是一个🟢工具 —— 获取一个联系人、其公司和该公司的交易，单次请求即可完成。 | | **原始请求逃生口** | `hubspot_api_request`可访问新的或测试中的端点 —— 认证、限流和重试仍然在服务器端处理。 | | **两种传输方式：stdio和Streamable HTTP** | 在Claude Desktop本地使用，或运行一个始终在线的服务器，任意数量的MCP客户端都可以通过HTTP访问。 | | **Docker + docker-compose，健康检查，自动重启** | 生产环境部署开箱即用：`docker compose up`，它将保持运行。 | | **可选的承载令牌认证**，在HTTP端点上 | 将服务器置于共享密钥后面，一旦它在localhost之外可访问。 | | **您的令牌永远不会到达模型** | 访问令牌存储在服务器的环境中，并在每次请求时注入 —— 助手只会看到工具输入和API响应。 | | **直接规范更新** | `npm run fetch-specs`从HubSpot的公共索引中提取最新的OpenAPI定义（及其Hub/层级元数据）—— 新端点在重建时成为新工具，无需更改代码。 | ## 比较 今天有几种方法可以从AI助手访问HubSpot。以下是此服务器与其他服务器的比较： | | **此服务器** | 官方HubSpot MCP | shinzo-labs `hubspot-mcp` | `mcp-hubspot`（buryhuang） | CData MCP | |---|:---:|:---:|:---:|:---:|:---:| | 大约工具数量 | **~1,079** | ~7（远程） | 100+ | ~7 | 3（通用SQL） | | 完整的公共API（CRM **和** CMS · 营销 · 自动化 · 商务 · 文件 · 设置 · Webhook） | ✅ | ➖ CRM + 一些内容读取 | ➖ CRM中心 | ❌ | ❌ | | 每个工具的Hub和层级意识 | ✅ | ❌ | ❌ | ❌ | ❌ | | 帐户能力报告（范围 · 使用情况 · 解锁） | ✅ | ❌ | ❌ | ❌ | ❌ | | 读取 **和** 写入 | ✅ | ✅ | ✅ | ➖ 部分 | ❌ 只读 | | 精选的🟢 / 🟡 / 🔴安全类别 | ✅ | ➖ | ➖ | ➖ | n/a | | `readOnlyHint` / `destructiveHint`注释 | ✅ | ➖ | ➖ | ➖ | ➖ | | 只读模式 + 分组过滤 | ✅ | ❌ | ❌ | ❌ | 始终只读 | | 文件上传（多部分） | ✅ | ❌ | ❌ | ❌ | ❌ | | GraphQL直通 | ✅ | ❌ | ❌ | ❌ | ❌ | | 速率限制 + 自动重试（`429`/`5xx`） | ✅ | ➖ | ➖ | ❌ | ❌ | | `stdio`传输 | ✅ | ✅ 本地包 | ✅ | ✅ | ✅ | | Streamable-HTTP传输 | ✅ | ✅托管远程 | ✅ | ❌ | ❌ | | Docker + compose + 健康检查 | ✅ | ❌ | ➖ Dockerfile | ➖ 仅镜像 | ❌ | | 自主托管在您自己的基础设施上 | ✅ | ➖ 供应商云 | ✅ | ✅ | ✅ | | 语言 | TypeScript | TypeScript | TypeScript | Python | Java | | 许可证 | MIT | — | MIT | MIT | MIT | _{✅ = 是 · ➖ = 部分 / 未记录 · ❌ = 否。从每个项目的公开文档中编译；这是一个非官方项目，与HubSpot或列出的项目无关。工具数量是近似的，随着API的演变而变化。} **简短版本：** 官方远程服务器是一个很好的托管入口，但它涵盖了少数精选的工具。社区服务器很不错，但以CRM为中心，没有计划意识或安全防护措施。这个服务器提供**整个公共API**、**其他服务器没有的Hub/计划意识**、**两种传输方式**、**生产环境的Docker部署**和**精选的安全类别** —— 自主托管，在您的令牌上，MIT许可证。 ## 您可以用它做什么 连接后，您可以问您的助手类似的问题： - “找到jane@example.com，显示她的公司，打开的交易和我们交换的最新电子邮件。” - “在销售管道中创建一个$12,000的交易‘Acme扩展’，阶段合格，并与Acme Corp关联。” - “搜索本月创建的生命周期阶段为MQL的联系人，并将他们添加到‘Q3培育’列表中。” - “哪些HubDB表存在？添加一行到‘pricing’并发布表格。” - “克隆上个月的新闻稿作为草稿 —— 不要发布。” - “上传此CSV文件并启动一个联系人导入，映射到电子邮件 + 名称。” - “我的令牌能做什么？检查我的API使用情况和哪些范围缺失以获取HubDB。”（→ `hubspot_get_capabilities`） - “合并这两个重复的联系人 —— 在显示两个记录后。” 工具会自动从HubSpot的规范中生成，并分为🟢只读、🟡写入和🔴破坏性类别，以便行为良好的主机可以区别对待每个类别。 ## 它是如何工作的 ``` Claude / Cursor / 任意MCP客户端 ──MCP──► 此服务器 ──HTTPS──► api.hubapi.com（您的门户） ``` 服务器解析104个捆绑的OpenAPI定义（从HubSpot的公共API索引中获取，也发布每个API的**Hub/层级需求**）到MCP工具 —— 解析 `$ref`、防止递归模式、派生干净的名称如`contacts_search`和`hubdb_tables_create_table`，并为每个工具添加精选的安全类别、计划需求和OAuth范围。您的访问令牌在服务器端注入每个请求；模型永远不会看到或处理它。 ## Hub和计划意识 HubSpot不是一个API —— 您可以调用的内容取决于**哪些Hub**（营销、销售、服务、内容、商务、运营）和**哪个层级**（免费、入门级、专业级、企业级）您的门户拥有，加上授予您的令牌的**范围**。此服务器围绕这一现实构建： 1. **每个工具描述都带有需求**，来自HubSpot自己的索引： ``` 🟢 只读 · Hubdb（CMS）· GET /cms/v3/hubdb/tables … 计划：营销Hub / 内容Hub的专业级。范围：hubdb。 ``` 2. **`hubspot_get_capabilities`** 报告 *您的* 门户和令牌的：帐户详细信息、授予的范围、今日API使用情况与每日上限，以及每个工具组您的令牌实际解锁了多少端点（`"unlockedByScopes": "13/16"`），解锁其余部分需要什么范围。传递`probe_groups: ["hubdb"]`以实时验证，验证成本极低。 3. **403返回修复**：缺少范围 → 恰好需要的范围及其位置；限制的API → HubSpot需要的层级。 ## 需求 - **HubSpot账户** 和 **私有应用访问令牌**（或OAuth访问令牌）—— 请参阅 [获取您的API凭证](#获取您的API凭证)。 - **Docker**（Docker Desktop适用于macOS/Windows）以便快速启动 —— 或 **Node.js ≥ 18** 以 [从源代码运行](#从源代码运行stdio无docker）。 ## 快速入门（Docker） **1. 添加您的凭证.** 复制示例配置并填写： ```bash cp .env.example .env # 编辑.env → 设置HUBSPOT_ACCESS_TOKEN # → 设置MCP_SHARED_TOKEN到一个长随机字符串，如果可从localhost以外的范围访问 ``` **2. 启动服务器： ```bash docker compose up -d --build ``` 捆绑的`docker-compose.yml`仅绑定到`127.0.0.1:8765`，因此服务器可从您的机器访问，但不能从网络访问。 **3. 确认它正在运行： ```bash curl -s http://localhost:8765/health # → {"status":"ok","server":"hubspot-mcp","tools":1079,"endpoints":1076,"mode":"all"} ``` **4. 连接您的MCP客户端.** MCP端点是`http://localhost:8765/mcp`。 - **Claude Desktop** — 添加一个**自定义连接器**（设置 → 连接器）指向 URL，或使用 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote）桥接本地与 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote）。添加此项到 `mcpServers`您的配置，然后完全退出并重新打开应用程序： ```json { "mcpServers": { "hubspot": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8765/mcp", "--header", "Authorization: Bearer YOUR_MCP_SHARED_TOKEN" ] } } ` （如果您留下了`MCP_SHARED_TOKEN`为空，请删除 `--header`行） - **Claude Code** — 一条命令： ```bash claude mcp add --transport http hubspot http://localhost:8765/mcp 工具可用那里。 > **提示：** 1,000+工具对一些客户端来说很多。使用`HUBSPOT_INCLUDE_GROUPS`（例如`contacts,deals,tickets,lists`）或设置`HUBSPOT_TOOL_MODE=discovery`以获取相同的覆盖范围，通过3个元工具 — [上下文占用](#上下文占用）以测量每个配置的数字。### 偏好预构建镜像？ 每次推送到`main`都会将预构建的镜像发布到GitHub容器注册表，因此您可以完全跳过本地构建：```bash docker run -d --name hubspot-mcp -p 127.0.0.1:8765:8765 --env-file .env ghcr.io/ohneben/hubspot-mcp:latest ``` ## 获取您的API凭证 推荐的方式是 **私有应用** 令牌： 1. 在HubSpot中，打开 **设置 → 集成 → 私有应用** 然后点击 **创建私有应用**。 2. 在 **作用域** 标签页，勾选您想要助手访问的内容。作用域与工具组一一对应 — 授予读取作用域 (`crm.objects.contacts.read`, …) 以进行报告设置，添加写入作用域仅在您希望进行更改的地方。您可以稍后更改作用域；能力报告显示了任何给定 组中缺少的内容。 3. 创建应用并复制 **访问令牌** (`pat-…`) → `.env` 中的 `HUBSPOT_ACCESS_TOKEN`。 注意： - **OAuth访问令牌** 也可以使用（适用于您构建的应用） — 但它们在约30分钟后过期，此服务器不会刷新它们；私有应用令牌是适合长期运行的服务器的正确选择。 - 令牌确定门户 — 无需门户ID。 - **欧盟数据驻地**: 如果您的门户位于HubSpot的欧盟数据中心，请设置 `HUBSPOT_BASE_URL=https://api-eu1.hubapi.com`. ## 配置 所有内容都设置在 `.env`（从 `.env.example` 复制而来）： | 变量 | 必需 | 默认值 | 描述 | |---|---|---|---| | `HUBSPOT_ACCESS_TOKEN` | ✅ | — | 私有应用令牌 (`pat-…`) 或 OAuth 访问令牌 | | `HUBSPOT_BASE_URL` | — | `https://api.hubapi.com` | 使用 `https://api-eu1.hubapi.com` 进行欧盟数据驻地 | | `MCP_TRANSPORT` | — | `stdio` | `stdio` 或 `http`（Docker镜像默认为 `http`） | | `PORT` | — | `8765` | HTTP监听端口 | | `HOST` | — | `0.0.0.0` | HTTP绑定地址 | | `MCP_HTTP_PATH` | — | `/mcp` | HTTP MCP 路由 | | `MCP_SHARED_TOKEN` | — | _(关闭)_ | 需要 `/mcp` 上的 `Authorization: Bearer <token>` | | `HUBSPOT_MAX_REQUESTS` | — | `100` | 客户端请求每窗口（`0` 禁用限流） | | `HUBSPOT_RATE_WINDOW_MS` | — | `10000` | 速率限制窗口（毫秒）（默认：100 请求 / 10 秒） | | `HUBSPOT_SEARCH_MAX_REQUESTS` | — | `4` | `/search` 端点的额外限制（`0` 禁用） | | `HUBSPOT_SEARCH_RATE_WINDOW_MS` | — | `1000` | 搜索速率限制窗口（默认：4 请求 / 秒） | | `HUBSPOT_MAX_RETRIES` | — | `3` | `429` / `5xx` / 网络错误时的重试次数 | | `HUBSPOT_TIMEOUT_MS` | — | `30000` | 每次尝试的请求超时时间 | | `HUBSPOT_READ_ONLY` | — | `false` | 仅暴露 🟢 只读工具 | | `HUBSPOT_INCLUDE_GROUPS` | — | _(全部)_ | 仅暴露这些组 — 键如 `contacts,deals` 和区域通配符如 `cms:*` | | `HUBSPOT_EXCLUDE_GROUPS` | — | _(无)_ | 隐藏这些组（语法相同） | | `HUBSPOT_INCLUDE_BETA` | — | `true` | 包括测试版 / 开发预览 API | | `HUBSPOT_TOOL_MODE` | — | `all` | `all`（每个端点一个工具）或 `discovery`（3 个元工具） | | `HUBSPOT_ENABLE_GRAPHQL` | — | `true` | 暴露 CRM GraphQL 查询工具 | | `HUBSPOT_GRAPHQL_URL` | — | _(派生)_ | 重写 GraphQL 端点 | | `HUBSPOT_ENABLE_RAW_REQUEST` | — | `true` | 暴露原始请求逃生口（在只读模式下自动隐藏） | | `HUBSPOT_MAX_RESPONSE_CHARS` | — | `0` | 将响应截断为 N 个字符（`0` = 永远不） | | `HUBSPOT_SPEC_DIR` | — | _(捆绑)_ | 从不同的目录加载 OpenAPI 文件 + catalog.json | 更改 `.env` 后，使用 `docker compose up -d --force-recreate` 重启。 运行 `npm run list-tools`（无需凭证）打印完整的工具目录、每个类别的计数和您可以在其上过滤的每个组键 — 添加 `--names` 列出所有 1,076 个工具名称。 ### 上下文占用 如果您想为某些客户端使用较小的上下文占用，请尝试使用 `HUBSPOT_INCLUDE_GROUPS`（例如 `contacts,companies,deals,tickets,lists`）或设置 `HUBSPOT_TOOL_MODE=discovery` 以获得相同的覆盖范围，但使用 3 个元工具。 ## 工具安全类别 每个工具的描述都以以下横幅之一开头，并带有匹配的 [MCP 注释](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations)： | 横幅 | 数量 | `readOnlyHint` | `destructiveHint` | 含义 | |---|:---:|:---:|:---:|---| | 🟢 **只读** | 348 | `true` | `false` | `GET` — 仅获取数据。安全。 | | 🟢 **只读 · 查询** | 95 | `true` | `false` | `POST` 查询（对象搜索、批量读取、导出启动、令牌检查）— 不更改记录。 | | 🟡 **写入 · 创建数据** | 245 | `false` | `false` | 创建记录（非幂等；可能重复）。 | | 🟡 **写入 · 创建或更新** | 36 | `false` | `false` | 幂等更新（批量更新、营销事件更新）。 | | 🟡 **写入 · 更新数据** | 168 | `false` | `false` | 修改记录/设置。 | | 🟡 **写入 · 连接记录** | 19 | `false` | `false` | 关联记录（列表成员资格、v4 关联）。可逆。 | | 🟡 **写入 · 断开记录** | 12 | `false` | `false` | 删除关联。 可逆 — 记录存活。 | | 🟡 **写入 · 发送消息** | 4 | `false` | `false` | 营销/交易电子邮件、序列注册、对话回复。 | | 🟡 **写入 · 批量导入** | 1 | `false` | `false` | `POST /crm/v3/imports` — 可以创建/更新数千条记录。 | | 🔴 **破坏性 · 删除数据** | 96 | `false` | `true` | 删除/归档记录（CRM 归档可恢复 ~90 天）。 | | 🔴 **破坏性 · 批量删除** | 42 | `false` | `true` | 批量归档 — 一次调用多个记录。 | | 🔴 **破坏性 · 合并记录** | 7 | `false` | `true` | HubSpot **无法取消合并**。请先确认两个 ID。 | | 🔴 **破坏性 · 永久 GDPR 删除** | 3 | `false` | `true` | 跳过回收站；永久删除。 | 这意味着 **443 只读 · 485 写入 · 148 破坏性 = 1,076 端点工具**， 加上下面的三个强力工具。尊重注释的主机（包括 Claude） 可以要求 `destructiveHint` 工具的确认，并自动信任 `readOnlyHint` 工具。 如果需要进一步锁定，请设置 `HUBSPOT_READ_ONLY=true` 以仅公开 443 个只读工具（以及 🟢 功能和 GraphQL 工具）。 <details> <summary><strong>按区域划分的覆盖率（API / 🟢 读取 / 🟡 写入 / 🔴 删除）</strong></summary> | 区域 | API | 🟢 读取 | 🟡 写入 | 🔴 删除 | 工具 | |---|:---:|:---:|:---:|:---:|:---:| | CRM | 58 | 216 | 245 | 92 | **553** | | CMS | 13 | 74 | 123 | 22 | **219** | | 营销 | 7 | 42 | 46 | 11 | **99** | | 对话 | 3 | 18 | 11 | 3 | **32** | | 自动化 | 3 | 17 | 10 | 4 | **31** | | Webhooks 日志 | 1 | 20 | 3 | 3 | **26** | | 设置 | 3 | 14 | 9 | 1 | **24** | | 文件 | 1 | 10 | 7 | 4 | **21** | | 通信偏好 | 1 | 6 | 8 | 0 | **14** | | 事件 | 3 | 4 | 7 | 2 | **13** | | Webhooks | 1 | 3 | 4 | 2 | **9** | | 数据工作室 | 1 | 1 | 6 | 1 | **8** | | 身份验证（OAuth） | 1 | 3 | 2 | 2 | **7** | | 账户 | 2 | 5 | 0 | 0 | **5** | | 商务 | 1 | 2 | 2 | 1 | **5** | | 调度器 | 1 | 3 | 2 | 0 | **5** | | 元数据 | 1 | 4 | 0 | 0 | **4** | | 业务单元 | 1 | 1 | 0 | 0 | **1** | | **总计** | **102** | **443** | **485** | **148** | **1,076** | </details> ## 上下文足迹 1,000 多个工具的成本是多少？在捆绑规格上测量 （`tools/list` JSON 有效载荷；令牌 ≈ 字符 ÷ 3.6）： | 配置 | 工具 | 有效载荷 | ≈ 令牌 | |---|---:|---:|---:| | 完整（默认） | 1,079 | 2.20 MB | ~612k | | 只读模式 | 445 | 0.61 MB | ~169k | | CRM 核心预设¹ | 176 | 0.29 MB | ~81k | | CRM 核心预设¹ + 只读 | 65 | 0.10 MB | ~28k | | **发现模式** | **6** | **0.01 MB** | **~2k** | _{¹ `HUBSPOT_INCLUDE_GROUPS=contacts,companies,deals,tickets,lists,properties,associations,pipelines,crm-owners,notes,tasks,calls,emails,meetings`} 如何阅读： - **具有工具搜索/延迟加载的客户端**（Claude Code，claude.ai 连接器）不会支付前期费用 — 工具定义按需加载， 因此完整模式是可以的，只有实际使用的工具才会进入上下文。 - **预先注入每个工具定义的客户端**应该选择一个杠杆： `HUBSPOT_TOOL_MODE=discovery`（~2k 令牌，**零覆盖率损失** — 所有 1,076 个端点仍然可以通过搜索 → 检查 → 调用）， 一个 `HUBSPOT_INCLUDE_GROUPS` 预设，和/或 `HUBSPOT_READ_ONLY=true`。 - **响应也会消耗上下文**。用 `HUBSPOT_MAX_RESPONSE_CHARS`（例如 `40000`）限制异常值，并请求 CRM 读取时仅需要的 `properties`。 ## 强力工具 除了生成的端点工具外，服务器还提供四个手工制作的工具： - **`hubspot_get_capabilities`** 🟢 — 上文描述的 capability 报告。 在会话中先调用它。 - **`hubspot_graphql_query`** 🟢 — HubSpot 的 CRM GraphQL API （`POST /collector/graphql`）。仅限查询设计（HubSpot 不公开突变），因此即使在只读模式下也可用。 需要 `collector.graphql_query.execute` 作用域和 Marketing/Content Hub Pro+。 - **`hubspot_api_request`** 🔴 — 任意路径的原始逃生口（新测试版、未文档化的角落）。 相同的身份验证注入、限流和重试。 在只读模式下隐藏。 - **发现模式** (`HUBSPOT_TOOL_MODE=discovery`) — 用 `hubspot_search_endpoints` → `hubspot_get_endpoint` → `hubspot_invoke_endpoint` 替换 1,076 个按端点工具。 仍然应用所有过滤器（组、测试版、只读）；在只读模式下，调用工具在物理上无法到达写入，因为写入不在注册表中。 ## 从源代码运行（stdio，无 Docker） 更喜欢 Claude Desktop 的经典_stdio 模式？ 在本地构建： ```bash npm install npm run build ``` 然后在 `claude_desktop_config.json` 中指向编译后的入口点： ```json { "mcpServers": { "hubspot": { "command": "node", "args": ["/ABSOLUTE/PATH/Hubspot-MCP/dist/index.js"], "env": { "MCP_TRANSPORT": "stdio", "HUBSPOT_ACCESS_TOKEN": "pat-na1-…" } } } } ``` ## 保持规格最新 `spec/` 下的捆绑文件是工具的真实来源。 它们是从 **HubSpot 自己的公共 API 索引** （`https://api.hubspot.com/public/api/spec/v1/specs`）获取的，该索引列出了每个公共 API 的每个版本 OpenAPI 文档 **和 hub/tier 要求**，此服务器将这些要求纳入工具描述中。 `spec/catalog.json` 记录了获取的内容（API、版本、阶段、测试版标志、要求、文档链接）。 要刷新 HubSpot 的最新版本： ```bash npm run fetch-specs # 覆盖 spec/*.json + spec/catalog.json npm run build && npm run list-tools ``` 新的端点会自动成为新的工具 — 无需代码更改。 获取脚本优先使用每个 API 的 **稳定经典版本**（v1/v3/v4），并在无法提供时回退到过时或测试版：某些 API 被固定为捆绑多个真正不同的版本（OAuth v1 + v3，通信偏好 v3 + v4）。 ## 开发 ```bash npm install npm run build # 编译 TypeScript → dist/ npm test # 运行 Vitest 套件（81 个测试） npm run list-tools # 打印分类的工具目录（不需要凭证） npm run fetch-specs # 从 HubSpot 的公共 API 索引刷新 spec/ ``` CI 在 Node 20 和 22 上构建和测试每次推送；推送到 `main` 也会发布到 GitHub 容器注册表。 ## 注释和约定 - **传输**：`MCP_TRANSPORT=stdio`（默认）适用于本地启动器；`MCP_TRANSPORT=http` 适用于 Docker 镜像运行的始终在线 Streamable-HTTP 服务器。 - **分页**：CRM 列表工具使用游标分页 — 传 `limit` 和 `paging.next.after` 的 `after` 游标。 通过 `properties` 参数请求您需要的属性（数组成为重复查询参数）。 - **搜索**：`*_search` 工具接受一个 JSON `body`，包含 `filterGroups`、`sorts`、`query`、`properties`、`limit` 和 `after`。 HubSpot 在每个令牌的 ~5 req/s 上限制搜索 — 内置搜索节流器使其保持在限制下。 - **批量工具**（`*_batch_read`、`*_batch_create`，…）是触摸许多记录的有效方法 — 优于单次调用的循环。 - **关联**：使用 v4 关联工具（`associations_*`）链接记录，可选标签通过关联模式工具。 - **文件上传**：多部分工具接受文件字段为 `{"fileName": "report.pdf", "contentBase64": "…"}` （或 `content` 用于纯文本）；其他字段作为常规表单字段发送，对象作为 JSON 字符串。 - **删除是归档**，适用于 CRM 对象（回收站，~90 天） — 真正永久的是 🔴 `gdpr_delete` 清除工具和记录合并。 - **速率限制**：HubSpot 按 10 秒强制突发上限（私有应用：100–200/10 秒取决于计划；OAuth 应用 ~110/10 秒）加上每日上限。 服务器在 `HUBSPOT_MAX_REQUESTS` 每个窗口内自我限制，并在收到 `429` 时重试，遵守 `Retry-After`。 通过 `hubspot_get_capabilities` 随时检查实际使用情况。 - **请求体**：写入工具接受一个 `body` 参数；其模式从规格中解析并显示给模型（例如 `contacts_create` 期望 `{"properties": {…}}`）。 - **测试版 API**（开发人员预览/公开测试版）默认包含，并在描述中用 ⚠️ 标记；使用 `HUBSPOT_INCLUDE_BETA=false` 隐藏它们。 ## 安全 - 您的访问令牌仅存在于 `.env` 中，该文件被 git 忽略。 **永远不要提交真正的机密。** 该令牌授予其作用域允许的任何权限 — 如果它泄漏，请在 **设置 → 集成 → 私有应用** 中旋转它。 - 默认情况下，HTTP 端点是未经身份验证的（在 localhost 上正常）。 要将其公开到您的机器之外，请设置 `MCP_SHARED_TOKEN` 并将其作为 `Authorization: Bearer <token>` 头部发送 — 理想情况下在 TLS 后面。 - 破坏性工具（删除 / **合并** / **GDPR 删除**）和 **发送** 工具（营销和交易电子邮件、序列）带有正确的注释，以便行为良好的主机在执行前提示 — 保持该确认开启，或运行 `HUBSPOT_READ_ONLY=true`。 - 在源处限制爆炸半径：仅授予私有应用实际需要的权限 — 功能报告将告诉您需要更多时缺少的内容。 参见 [SECURITY.md](./SECURITY.md) 以获取完整的安全策略和如何报告漏洞。 ## 致谢和许可 HubSpot 的非官方社区集成；与 HubSpot 无关联或背书。 建立在 [Model Context Protocol](https://modelcontextprotocol.io) 上。 工具从 HubSpot 的公共 OpenAPI 定义生成。 在 [MIT License](./LICENSE.md) 下许可。