HubSpot

ohneben 的 HubSpot MCP

---

许可证与检查

MCP 注册目录

这是目前功能最全面的 HubSpot MCP 服务。 通过 Claude、 Cursor 或任何其他 MCP 客户端，使用自然语言操作整个 HubSpot 账户。

此 Model Context Protocol 服务公开了 整个 HubSpot 公共 API——涵盖 102 个 API 的全部 1,076 个端点，封装为 687 个 工具——包括 CRM、CMS、Marketing、Automation、Conversations、Commerce、Files、 Settings、Webhooks 等，直接根据 HubSpot 自己的 OpenAPI 定义生成。HubSpot 按对象类型重复提供的端点各自只对应一个工具 （例如使用带有 objectType: "deals" 的 crm_objects_search，而非 32 个独立的搜索 工具），且每个工具的说明都会指出适用场景。每个工具都经过安全分类（🟢 只读 / 🟡 写入 / 🔴 破坏性操作），并且——这是本服务独有的——能够识别 Hub 和套餐：HubSpot 会公布每个 API 所需的 Hub 和套餐等级（Free / Starter / Professional / Enterprise），本服务会将这些信息直接纳入每个工具，并为你的门户提供实时的功能报告。它支持通过 stdio 运行（Claude Desktop 和其他本地启动器），也支持通过 Streamable HTTP 运行（托管于 Docker），并内置重试机制、针对 HubSpot 突发速率上限调优的客户端限流功能，以及请求超时设置，确保能够稳定连接实际账户。

为什么你会需要它

有些 MCP 服务只转发部分 API。本服务专为安全交由大模型使用、功能完整以及轻松用于实际场景而打造：

你将获得	重要性
全部 1,076 个端点 — 完整的公开 API	联系人、公司、交易、工单、所有互动类型、关联 v4、属性、管道、列表、导入/导出、营销邮件和事件、营销活动、表单、事务性邮件、序列、工作流/操作、对话和自定义渠道、CMS 页面/帖子/HubDB/源代码、文件、电商（发票、订单、购物车、付款、订阅）、设置、Webhook — 无一遗漏，也没有经过挑选。大多数服务只支持约 30 个 CRM 工具。
687 个工具，而非 1,076 个换名重复项	HubSpot 会针对 32 种 CRM 对象类型、着陆页和网站页面，以及博客帖子、作者和标签重复提供相同端点。这些各自都只对应一个工具，并通过选择器参数（objectType、pageType、blogResource）指定对象，因此 crm_objects_search 就能覆盖联系人、交易、工单和自定义对象。每次调用仍会准确请求原先对应的端点，并遵循该端点的权限范围和套餐要求。
说明何时使用工具的描述	每条描述都先说明工具的作用，再说明何时优先使用同类工具（crm_objects_list 会指向用于筛选的 crm_objects_search，以及用于已知 ID 的 crm_objects_batch_read）、工具会更改什么、套餐和权限范围，以及调用的端点。未在 HubSpot 文档中说明的参数也会附上描述。
了解 Hub 和套餐 （其他服务都没有）	HubSpot 会根据 Hub 和套餐等级限制 API — HubDB 需要 Content/Marketing Hub Professional，自定义对象架构需要 Enterprise，序列需要 Sales/Service Professional。每个工具都会注明所需条件，信息直接来自 HubSpot 自己的 API 索引。
启动时检查访问权限	服务启动时会读取令牌的权限范围，并通过一次成本低廉的读取请求探测每个付费套餐或 Beta API 组。模型会在服务说明中收到检查结果，搜索结果会逐个工具说明此令牌能否使用该工具，而 hubspot_get_capabilities 则会说明每种状态及需要添加的权限范围。不再被令人摸不着头脑的 403 错误拦住。
精心设计的安全类别 🟢 / 🟡 / 🔴	不会天真地认为“GET = 安全”：POST …/search 是只读查询，merge 标记为不可逆，gdpr-delete 是永久清除（不同于移入回收站的归档操作），列表成员关系调用是可逆的关联，POST /crm/v3/imports 是批量导入，而事务性邮件会发送消息。
机器可读的 MCP 注解（readOnlyHint、destructiveHint）	支持注解的宿主（包括 Claude）可以自动信任读取操作，并在执行任何破坏性操作前要求确认。
可操作的错误提示	MISSING_SCOPES 导致的 403 → 告知要添加哪些确切权限范围以及在哪里添加；受限 API 的普通 403 → 告知所需套餐等级；401 → 提供令牌类型和过期相关指导；429 → 告知你的请求限制。模型得到的是如何修复，而不只是出了什么问题。
只读模式和组筛选	只开放 302 个 🟢 只读工具（HUBSPOT_READ_ONLY=true），或缩小范围，仅启用你使用的工具组（HUBSPOT_INCLUDE_GROUPS=contacts,deals,cms:*）。也支持区域通配符。
默认启用发现模式	开箱即用时，模型只会看到 6 个工具（约 2k 个 token）：可对全部 687 个端点工具进行搜索、检查和调用的工具，以及功能、GraphQL 和原始请求工具。设置 HUBSPOT_TOOL_MODE=all 可直接开放全部端点工具。无论使用哪种模式，都适用只读模式。
真正的文件上传	多部分请求端点（Files、CRM 导入、HubDB 导入、CMS 源代码）可以正常工作 — 可直接传入文件内容或以 base64 格式传入。大多数生成式服务根本不支持多部分请求。
自动重试与退避	遇到临时 429 / 5xx 响应时，会采用带随机抖动的指数退避进行重试，并遵循 HubSpot 的 Retry-After 标头。
内置速率限制	会在 HubSpot 的突发请求上限内自动限制速率（默认 100 个请求 / 10 秒），并为 /search 端点设置单独的限速器（上限约为 5 个请求/秒）。工具调用突发不会触发 429。
响应大小保护	可选限制超大列表响应（HUBSPOT_MAX_RESPONSE_CHARS），避免单次调用撑爆模型的上下文窗口。
CRM GraphQL 直通	HubSpot 的 GraphQL 端点仅支持查询，因此在这里属于 🟢 工具 — 一次往返即可获取联系人、其所属公司以及该公司的交易。
原始请求备用通道	HubSpot 一发布全新或 Beta 端点，hubspot_api_request 就能立即访问 — 身份验证、限速和重试仍由服务端处理。
两种传输方式：stdio 和 Streamable HTTP	可在 Claude Desktop 中本地使用，也可运行一个始终在线的服务，让任意数量的 MCP 客户端通过 HTTP 访问。
Docker + docker-compose、健康检查、自动重启	开箱即提供适用于生产环境的部署方式：运行 docker compose up 即可持续运行。
HTTP 端点可选的持有者令牌身份验证	只要服务可从 localhost 以外的位置访问，就可立即将其置于共享密钥保护之下。
令牌永远不会传给模型	访问令牌保存在服务的环境中，并在每次请求时注入 — 助手只会看到工具输入和 API 响应。
直接更新规范	npm run fetch-specs 会从 HubSpot 的公开索引获取 HubSpot 最新的 OpenAPI 定义（以及 Hub 和套餐元数据）— 重新构建后，新端点就会成为新工具，无需更改代码。

对比

如今，AI 助手有几种方式可以连接 HubSpot。下面是此服务与其他方案的对比：

	此服务	官方 HubSpot MCP	shinzo-labs hubspot-mcp	mcp-hubspot（buryhuang）	CData MCP
工具数量（约）	约 690 个（覆盖全部 1,076 个端点）	约 7 个精选工具（远程）	100+	约 7 个	3 个（通用 SQL）
完整公共 API（CRM 以及 CMS · Marketing · Automation · Commerce · Files · Settings · Webhooks）	✅	➖ CRM + 部分内容读取	➖ 以 CRM 为主	❌	❌
每个工具均感知 Hub 和套餐等级	✅	❌	❌	❌	❌
账户能力报告（权限范围 · 用量 · 可解锁项）	✅	❌	❌	❌	❌
读取和写入	✅	✅	✅	➖ 部分支持	❌ 只读
精选 🟢 / 🟡 / 🔴 安全类别	✅	➖	➖	➖	不适用
readOnlyHint / destructiveHint 注解	✅	➖	➖	➖	➖
只读模式 + 分组筛选	✅	❌	❌	❌	始终只读
文件上传（multipart）	✅	❌	❌	❌	❌
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 许可证。

你可以做什么

连接后，可以向助手提出类似这样的请求：

• “查找 [email protected]，显示她的公司、未结交易以及我们最近交换的邮件。”
• “在 Sales 销售渠道中创建一笔 $12,000 的交易，名称为 ‘Acme expansion’，阶段为 Qualified，并关联到 Acme Corp。”
• “搜索本月创建、生命周期阶段为 MQL 的联系人，并将他们添加到 ‘Q3 nurture’ 列表。”
• “有哪些 HubDB 表？在 ‘pricing’ 中添加一行并发布该表。”
• “将上个月的新闻简报克隆为草稿——不要发布。”
• “上传此 CSV，并开始导入联系人，将电子邮件 + 名字映射到对应字段。”
• “我的令牌能做什么？检查我的 API 用量，以及使用 HubDB 还缺少哪些权限范围。” （→ hubspot_get_capabilities）
• “合并这两个重复联系人——先向我展示两条记录。”

工具根据 HubSpot 的规范自动生成，并分为 🟢 只读、🟡 写入和 🔴 破坏性操作三类——因此，行为规范良好的宿主可以区别对待每个类别。

工作原理

Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  api.hubapi.com (your portal)

此服务会将 104 份打包的 OpenAPI 定义（从 HubSpot 的公共 API 索引获取，该索引还会公布每个 API 的Hub／套餐要求）解析为 MCP 工具——解析 $ref、防范递归架构、将仅对象类型不同的端点合并为一个工具、生成 crm_objects_search 和 hubdb_tables_create_table 之类的简洁名称，并为每个工具标注精选安全类别、套餐要求及 OAuth 权限范围。每次请求都会在服务端注入你的访问令牌；模型不会看到或处理该令牌。

Hub 与套餐感知

HubSpot 并非只有一个 API——你可以调用哪些 API，取决于门户拥有哪些中心（Marketing、 Sales、Service、Content、Commerce、Operations）、套餐等级（Free、 Starter、Professional、Enterprise），以及令牌获授的作用域。此服务围绕这一现实构建：

1. 每个工具描述都注明了要求，信息来自 HubSpot 自己的索引：

   🟢 READ-ONLY · Get all published tables.
   Use to page through tables: pass limit, then the after cursor from paging.next.after for the next page.
   …
   Plan: Professional tier of Marketing Hub / Content Hub. Scopes: hubdb.
   Endpoint: GET /cms/v3/hubdb/tables (Hubdb API, CMS)
   

   整合工具会按值注明要求：crm_objects_list 会在其 objectType 参数中列出哪些 对象类型需要付费套餐。

2. 服务启动时会运行访问检查。 HubSpot 没有 API 可以返回门户的订阅信息，因此服务会结合 可观测到的信息：令牌获授的作用域，以及对每个付费套餐或 Beta 分组进行一次低成本读取（最多约 30 次 API 调用；套餐限制只会以 403 状态码呈现）。每个分组都会获得一个状态：available、 missing_scopes、blocked（套餐等级、用户权限，或某个不接受此类令牌的 API 返回的 401） 或 unverified。HubSpot 的错误详情很重要：如果 403 指明令牌缺少某些作用域，就表示缺少作用域； 如果某个对象所需的作用域已在令牌中，但 HubSpot 返回 MISSING_SCOPES，这就是 HubSpot 对套餐限制的 响应，因此会报告为受阻。读取成功只能证明具有读取权限；付费套餐 API 仍可能拒绝写入操作，报告会说明这一点。 模型会在服务说明中收到摘要，hubspot_search_endpoints 会标记每条结果（并接受 usable_only: true），而 hubspot_get_capabilities 会返回包含原因的完整报告、 "unlockedByScopes": "13/16" 计数以及需要添加的作用域；refresh: true 会再次运行检查。 使用 HUBSPOT_CAPABILITY_CHECK=false 可关闭此功能。

3. 403 会附带解决办法：缺少作用域 → 显示确切的作用域名称以及授予位置；API 受套餐限制 → 显示 HubSpot 要求的套餐等级。

要求

• 一个 HubSpot 账户和一个服务密钥（或现有的旧版私有应用令牌）；请参阅获取 API 凭据。
• 以下快速入门需要 Docker（macOS/Windows 上使用 Docker Desktop）——或者使用 Node.js ≥ 18 从源代码运行。

快速入门（Docker）

1. 添加凭据。 复制示例配置并填写：

cp .env.example .env
# edit .env → set HUBSPOT_ACCESS_TOKEN
#           → set MCP_AUTH_TOKEN. REQUIRED unless HOST is a loopback address,
#             otherwise the server refuses to start: MCP_AUTH_TOKEN=$(openssl rand -hex 32)

2. 启动服务：

docker compose up -d --build

附带的 docker-compose.yml 仅绑定到 127.0.0.1:8765，因此服务可从你的计算机访问，但无法从网络访问。

3. 确认服务正在运行：

curl -s http://localhost:8765/health
# → {"status":"ok","server":"hubspot-mcp"}

4. 连接 MCP 客户端。 MCP 端点为 http://localhost:8765/mcp。

• Claude Desktop — 添加一个指向该 URL 的自定义连接器（Settings → Connectors），或者使用 mcp-remote 在本地桥接。将以下内容添加到配置中的 mcpServers 下，然后完全退出并重新打开应用：

  {
    "mcpServers": {
      "hubspot": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "http://localhost:8765/mcp",
          "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
        ]
      }
    }
  }
  

  （只有在服务未设置令牌、且仅绑定到环回地址时，才省略 --header 行。）

• Claude Code — 运行一条命令：

  claude mcp add --transport http hubspot http://localhost:8765/mcp
  

• Claude Cowork — 与 Claude Code 共用 MCP 配置，因此上述命令也会让这些工具在其中可用。

提示： 默认情况下，模型会看到 6 个工具，并通过搜索 → 检查 → 调用访问所有端点。如需每个端点 对应一个工具，请设置 HUBSPOT_TOOL_MODE=all（690 个工具），并使用 HUBSPOT_INCLUDE_GROUPS 进行筛选（例如 contacts,companies,deals,tickets,lists）——各项配置的测量数据请参阅 上下文占用。

更希望使用预构建镜像？

每次推送到 main 时，都会向 GitHub Container Registry 发布一个可直接运行的镜像，因此你可以完全跳过本地构建：

docker run -d --name hubspot-mcp -p 127.0.0.1:8765:8765 --env-file .env \
  ghcr.io/ohneben/hubspot-mcp:latest

获取 API 凭据

推荐使用服务密钥，这是 HubSpot 用来取代旧版私有应用的方案：

1. 在 HubSpot 中，打开 设置 → 集成 → 服务密钥（或 开发 → 密钥 → 服务密钥），然后创建密钥。你需要超级管理员权限或 Developer tools access 权限。
2. 选择希望助手能够访问的范围。范围与工具组一一对应：如果用于报告，可授予读取范围（crm.objects.contacts.read，……）；只在需要进行更改的地方添加写入范围。
3. 复制密钥（pat-…），并将其填入 .env 中的 HUBSPOT_ACCESS_TOKEN。它与私有应用令牌一样，以持有者令牌的形式发送，因此无需进行其他更改。

注意：

• 服务密钥目前处于公开测试阶段，与私有应用相比有三点区别需要注意：它们不支持 GraphQL（设置 HUBSPOT_ENABLE_GRAPHQL=false）；轮换密钥后，旧密钥在 7 天宽限期内仍然有效；能力报告中的范围和用量数据可能不完整。

• 现有私有应用令牌仍可使用。 HubSpot 将停止创建新的旧版私有应用（现有门户从 2026 年 10 月 26 日起，新门户从 2026 年 9 月 28 日起）；已创建的应用不受影响。如果依赖 GraphQL 工具，私有应用仍是此处唯一可用的选项。

• 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.api.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_AUTH_TOKEN	⚠️	(关闭)	要求对 /mcp 携带 Authorization: Bearer <token>。当 HOST 不是环回地址时，此项为必填，否则服务会拒绝启动。已在 1.1.0 中从 MCP_SHARED_TOKEN 更名
MCP_ALLOWED_HOSTS	—	(自动推导)	以逗号分隔的主机名列表，Host 标头可使用这些主机名。绑定到环回地址时，默认使用环回名称；位于反向代理后时，默认不进行检查
MCP_ALLOW_INSECURE	—	0	在非环回绑定地址上不使用令牌启动。仅适用于确实无法被他人访问的端口
MCP_BODY_LIMIT	—	25mb	可接受的最大请求正文大小
MCP_SESSION_TTL	—	1800	空闲会话在被清理前保留的秒数
MCP_MAX_SESSIONS	—	256	并发会话数上限；超出时会逐出最近最少使用的会话
HUBSPOT_MAX_REQUESTS	—	100	每个时间窗口内客户端请求数（0 表示禁用限流）
HUBSPOT_RATE_WINDOW_MS	—	10000	限流时间窗口，单位为毫秒（默认：每 10 秒 100 个请求）
HUBSPOT_SEARCH_MAX_REQUESTS	—	4	对 /search 端点的额外限流（0 表示禁用）
HUBSPOT_SEARCH_RATE_WINDOW_MS	—	1000	搜索限流时间窗口（默认：每 1 秒 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	包含 Beta 版／开发者预览 API
HUBSPOT_TOOL_MODE	—	discovery	discovery（覆盖整个目录的 3 个元工具）或 all（每个端点或端点系列提供一个工具）
HUBSPOT_CAPABILITY_CHECK	—	true	启动时读取令牌的权限范围，并探测付费套餐或 Beta 分组（最多约 30 次 API 调用）
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 可列出全部 687 个工具名称及其调用的端点。

工具安全类别

每个工具的描述都以以下横幅之一开头，并带有对应的 MCP 注解：

横幅	工具	端点	readOnlyHint	destructiveHint	含义
🟢 只读	274	348	true	false	GET — 仅获取数据。安全。
🟢 只读 · 查询	28	95	true	false	执行搜索/读取的 POST（对象搜索、批量读取、启动导出、令牌内省）——不会更改任何记录。
🟡 写入 · 创建数据	133	198	false	false	创建记录（非幂等；可能产生重复项）。
🟡 写入 · 创建或更新	7	36	false	false	幂等式插入或更新（批量插入或更新、营销事件插入或更新）。
🟡 写入 · 更新数据	131	215	false	false	原位修改记录/设置，包括发布、排期和恢复现有内容。
🟡 写入 · 关联记录	18	19	false	false	关联记录（列表成员关系、v4 关联）。可撤销。
🟡 写入 · 取消关联记录	11	12	false	false	移除关联。可撤销——记录仍会保留。
🟡 写入 · 发送消息	4	4	false	false	营销/交易电子邮件、加入序列、回复会话。
🟡 写入 · 批量导入	1	1	false	false	POST /crm/v3/imports — 可创建/更新数千条记录。
🔴 破坏性 · 删除数据	64	96	false	true	删除/归档记录（CRM 归档可在约 90 天内恢复）。
🔴 破坏性 · 批量删除	10	42	false	true	批量归档——一次调用处理多条记录。
🔴 破坏性 · 合并记录	3	7	false	true	HubSpot 无法撤销合并。请先确认两个 ID。
🔴 破坏性 · 永久 GDPR 清除	3	3	false	true	跳过回收站；永久删除。

总计 302 个只读 · 305 个写入 · 80 个破坏性工具端点 （443 · 485 · 148 = 1,076 个端点），此外还有以下三个强大工具。 支持注解的宿主（包括 Claude）可以要求对带有 destructiveHint 的工具进行确认，并自动信任带有 readOnlyHint 的工具。想要进一步限制权限？设置 HUBSPOT_READ_ONLY=true，即可仅公开 302 个只读工具（以及 🟢 能力工具和 GraphQL 工具）。

按领域划分的覆盖范围（API / 端点：🟢 只读 / 🟡 写入 / 🔴 破坏性 / 工具）

领域	API	🟢 只读	🟡 写入	🔴 删除	端点	工具
CRM	58	216	245	92	553	211
CMS	13	74	123	22	219	172
营销	7	42	46	11	99	99
会话	3	18	11	3	32	32
自动化	3	17	10	4	31	31
Webhooks 日志	1	20	3	3	26	26
设置	3	14	9	1	24	24
文件	1	10	7	4	21	21
通信偏好	1	6	8	0	14	14
事件	3	4	7	2	13	13
Webhooks	1	3	4	2	9	9
Data Studio	1	1	6	1	8	8
身份验证（OAuth）	1	3	2	2	7	7
账户	2	5	0	0	5	5
Commerce	1	2	2	1	5	5
Scheduler	1	3	2	0	5	5
Meta	1	4	0	0	4	4
业务单元	1	1	0	0	1	1
总计	102	443	485	148	1,076	687

## 上下文占用

工具列表会占用多少模型上下文？根据随附的规范测得 （tools/list JSON 负载；Token 数 ≈ 字符数 ÷ 3.6）：

配置	工具数	负载	≈ Token 数
发现模式（默认）	6	0.01 MB	~2k
HUBSPOT_TOOL_MODE=all	690	1.33 MB	~370k
all + 只读	304	0.38 MB	~104k
all + CRM 核心预设¹	85	0.13 MB	~36k
all + CRM 核心预设¹ + 只读	33	0.04 MB	~12k

在发现模式下，每次 hubspot_get_endpoint 查找只会添加模型请求的架构：典型端点约 350 个 Token，最大的 CMS 页面正文则高达约 12k。

_{¹ HUBSPOT_INCLUDE_GROUPS=contacts,companies,deals,tickets,lists,properties,associations,pipelines,crm-owners,notes,tasks,calls,emails,meetings}

如何理解这些数据：

• 发现模式不会减少覆盖范围：全部 1,076 个端点仍可通过搜索 → 检查 → 调用的方式使用，代价是模型首次使用某个端点时需要额外调用一两次。
• 支持工具搜索／延迟加载的客户端（Claude Code、claude.ai 连接器）会按需加载工具定义，因此 HUBSPOT_TOOL_MODE=all 在这些客户端上效果良好；可使用 HUBSPOT_INCLUDE_GROUPS 预设和／或 HUBSPOT_READ_ONLY=true 缩小范围。
• 响应也会占用上下文。 使用 HUBSPOT_MAX_RESPONSE_CHARS（例如 40000）限制异常大的响应，并在读取 CRM 数据时只请求所需的 properties。
• 已处理过大的内联架构：四个异常的递归架构（列表筛选器、工作流定义——完全内联时每个约 1.7 MB）会经过预算裁剪至 ≤24 KB，同时保留顶层内容。输入架构也会移除示例和正文自身字段之外的所有说明文字；所有字段、类型、枚举和必填列表均会保留。

强大工具

除生成的端点工具外，该服务还提供四个手工编写的工具：

• hubspot_get_capabilities 🟢 — 上文 HubSpot 计划与权限说明 中介绍的访问权限报告。返回启动时的检查结果，不会发起新的 API 调用；设置 refresh: true 可重新运行检查。
• hubspot_graphql_query 🟢 — HubSpot 的 CRM GraphQL API（POST /collector/graphql）。此工具仅用于查询（HubSpot 不提供 mutation），因此即使处于只读模式也仍可用。需要 collector.graphql_query.execute 权限范围以及 Marketing/Content Hub Pro+。
• hubspot_api_request 🔴 — 用于访问 HubSpot 主机上任意路径的原始后备入口（适用于新的 beta 功能和未公开的功能）。使用相同的身份验证注入、限流和重试机制。只读模式下会隐藏此工具。
• 发现模式（默认）— 用 hubspot_search_endpoints → hubspot_get_endpoint → hubspot_invoke_endpoint 取代 687 个端点工具，使用相同的注册表。所有筛选条件（分组、beta、只读）仍然适用；在只读模式下，invoke 工具实际上无法执行写入，因为注册表中不包含写入操作。

从 1.x 升级

2.0 将 HubSpot 按对象类型重复提供的端点合并为一个带有选择器参数的工具。每个端点仍可访问，发送的请求也相同；只有工具名称和少数参数名称会变化。请更新引用工具名称的已保存提示词、客户端允许列表和权限规则。HUBSPOT_INCLUDE_GROUPS / HUBSPOT_EXCLUDE_GROUPS 的分组键（contacts、deals、pages 等）保持不变。

1.x 工具	2.0 工具	参数
contacts_list、deals_list、tickets_list、… custom_objects_list	crm_objects_list	objectType: "contacts"（或 "deals"、"0-3"、自定义值 "2-12345" 等）
<type>_get、<type>_update、<type>_archive（部分工具为 <type>_delete）	crm_objects_get、crm_objects_update、crm_objects_archive	objectType；记录 ID 参数从 contactId、dealId 等改为 objectId
<type>_create、<type>_search、<type>_merge、<type>_batch_read / _create / _update / _upsert / _archive	crm_objects_create、crm_objects_search、crm_objects_merge、crm_objects_batch_*	objectType
partner_clients_associations_*、partner_services_associations_*	crm_objects_associations_list / _create / _delete	objectType: "partner_clients" 或 "partner_services"、objectId
pages_landing_*、pages_site_*	cms_pages_*，例如 cms_pages_draft_push_live	pageType: "landing" 或 "site"
posts_blogs_*、authors_blogs_*、tags_blogs_*，用于列出、获取、归档、批量读取/更新/归档及多语言操作	cms_blog_*，例如 cms_blog_list	blogResource: "posts"、"authors" 或 "tags"

保持不变：仅适用于一种类型的端点（contacts_gdpr_delete、着陆页文件夹、博客文章草稿和修订版，以及请求体因资源而异的博客创建/更新端点）。npm run list-tools -- --names 会打印每个工具及其调用的端点。用于发布、安排发布时间或恢复现有内容的 POST 端点，现在标记为 🟡 更新数据，而不是 创建数据。

还有两项默认设置会变化：HUBSPOT_TOOL_MODE 现在为 discovery（设为 all 可公开端点工具本身），并且服务会在启动时运行访问检查，每次启动最多约消耗 30 次 API 调用（设置 HUBSPOT_CAPABILITY_CHECK=false 可关闭检查）。

从源代码运行（stdio，无需 Docker）

更喜欢在 Claude Desktop 中使用经典的 stdio 模式？请在本地构建：

npm install
npm run build

然后在 claude_desktop_config.json 中将 Claude Desktop 指向编译后的入口文件：

{
  "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 和层级要求。spec/catalog.json 记录了获取的信息（API、版本、阶段、beta 标志、要求、文档链接）。

要与 HubSpot 的最新信息同步：

npm run fetch-specs   # rewrites spec/*.json + spec/catalog.json
npm run build && npm run list-tools

新端点会自动成为新工具，无需修改代码。获取脚本优先选择每个 API 的稳定经典版本（v1/v3/v4）；如果 HubSpot 仅提供带日期的版本或 beta 版本，则使用这些版本。少数 API 会固定使用多个确实不同的版本（OAuth v1 + v3、Communication Preferences v3 + v4）。

开发

npm install
npm run build       # compile TypeScript → dist/
npm test            # run the Vitest suite (160 tests)
npm run list-tools  # print the categorized tool catalog (no credentials needed)
npm run fetch-specs # refresh spec/ from HubSpot's public API index

CI 会在 Node 20 和 22 上构建并测试每次推送；推送到 main 时还会将 Docker 镜像发布到 GitHub Container Registry。

说明与约定

• 传输方式：本地启动器默认使用 MCP_TRANSPORT=stdio； Docker 镜像运行的常驻 Streamable-HTTP 服务使用 MCP_TRANSPORT=http。
• 分页：CRM 列表工具使用游标分页——传入 limit，以及从 paging.next.after 获取的 after 游标。通过 properties 参数指定所需属性（数组会转换为重复的查询参数）。
• 选择器：整合工具使用 objectType（crm_objects_*）、pageType（cms_pages_*）或 blogResource（cms_blog_*）。objectType 接受名称（contacts、line_items）、objectTypeId（0-3）和自定义对象类型（2-12345）。
• 搜索：crm_objects_search 和其他 *_search 工具接收包含 filterGroups、sorts、query、properties、limit 和 after 的 JSON body。HubSpot 将每个令牌的搜索速率限制为约 5 req/s；内置搜索限流机制会确保请求速率不超出限制。
• 批量工具（crm_objects_batch_read、crm_objects_batch_create……）是处理大量记录的高效方式——优先使用它们，而不是循环进行单次调用。
• 关联：使用 v4 关联工具（associations_*）关联记录；还可通过关联架构工具设置可选标签。
• 文件上传：multipart 工具接受以下格式的文件字段：{"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 参数；其架构会根据规范解析并展示给模型（例如，crm_objects_create 需要 {"properties": {…}}）。
• Beta API（开发者预览版 / 公开测试版）默认包含在内，并在描述中标记为 ⚠️；设置 HUBSPOT_INCLUDE_BETA=false 可隐藏它们。

安全

• 访问令牌仅保存在 .env 中，该文件已被 git 忽略。**切勿提交真实密钥。**令牌拥有其授权范围允许的所有权限——如果令牌泄露，请在 Settings → Integrations → Service Keys（旧版令牌则在 Private Apps）中将其停用。
• HTTP 端点绑定到本机以外的地址后，若未通过身份验证便会拒绝启动。设置 MCP_AUTH_TOKEN（openssl rand -hex 32），并通过 Authorization: Bearer <token> 标头发送令牌；建议在 TLS 后方运行。本地环回绑定无需令牌，并会通过 Host 标头检查额外防范 DNS 重绑定。
• 破坏性工具（删除 / 合并 / GDPR 清除）和发送工具（营销及事务性电子邮件、序列）带有相应注释，以便行为规范的宿主在执行前进行确认——请保持确认开启，或使用 HUBSPOT_READ_ONLY=true 运行。
• 从源头限制影响范围：仅为服务密钥授予实际需要的权限范围——启动时的访问检查和 hubspot_get_capabilities 会在你需要更多权限时告知缺少哪些范围。检查本身只会读取数据。

完整政策及漏洞报告方式请参阅 SECURITY.md。

鸣谢与许可证

一个非官方的社区版 HubSpot 集成；与 HubSpot 无关联，也未获得 HubSpot 背书。基于 Model Context Protocol 构建。工具由 HubSpot 的公开 OpenAPI 定义生成。采用 MIT License 许可。