HubSpot MCP

HubSpot + AI - 适用于 ChatGPT、Claude、GitHub Copilot、Microsoft 365 Copilot、Gemini，以及任何支持 MCP 的 Agent

非官方。由社区构建的 Claude Code Skill 和 HubSpot API 的 MCP 服务。与 HubSpot Inc. 无关联，未获其认可或赞助。

_{▶ 观看 30 秒演示 - 演示数据为模拟数据；展示的每条命令都存在于实际 CLI 中。}

涵盖 HubSpot Sales Hub 的所有功能，另有离线跨对象查询、属性变更历史报告，以及其他 HubSpot 工具都不具备的 Agent 原生数据层。可与您已在使用的 AI 配合使用——ChatGPT（Plus/Pro+，此连接器重新发布前暂停使用；请参阅 mcp-install.md）、Claude Desktop、Codex、Claude Code、Claude Cowork 和 GitHub Copilot——还可通过远程方式使用 Microsoft 365 Copilot / Copilot Studio 和 Google Gemini。免费、开源，可在您的笔记本电脑上运行。专为 MSP 所有者打造。无需编写代码。

适用于您的 Agent

安全说明（此连接器重新发布前）。 请勿运行 HTTP 模式 （--transport http），即使是在本地主机上也不行。此构建会检查令牌，但 尚未包含修复版本中的请求大小和时间限制。MCP 工具还可以使用您的凭据 执行更改。如果您为远程 Agent 设置了隧道，请将其关闭。修复即将推出。

MSP 所有者实际使用的六款 Agent（可自行安装，现已可用）：

您的 AI Agent	如何安装 HubSpot 技能
Claude Desktop	运行安装程序，然后前往 Settings > Extensions 注册 hubspot-mcp（无需编辑 JSON）。
ChatGPT（付费方案）	此连接器重新发布前暂停使用：ChatGPT 需要 HTTP 模式，而此构建中的该模式虽然会检查令牌，但尚无请求大小或时间限制。请参阅 mcp-install.md 中的安全说明。
Codex CLI	粘贴下方的安装提示词。
Claude Code	粘贴下方的安装提示词。
Claude Cowork	粘贴下方的安装提示词。
GitHub Copilot（VS Code）	运行安装程序，将 hubspot-mcp 添加到 mcp.json 的 servers 键下，然后选择 Agent 模式。

ChatGPT 需要远程 HTTPS 服务，也就是说需要使用此连接器的 HTTP 模式；在连接器重新发布前，该模式暂停使用：此构建中的该模式虽然会检查令牌，但尚无请求大小或时间限制。请参阅 mcp-install.md 中的安全说明。

Microsoft 和 Google 技术栈也适用

用户基数庞大，但请注意：以下是远程／企业版路径，而不是你刚刚安装的本地二进制文件。

Agent	所需操作
Microsoft 365 Copilot / Copilot Studio	暂停使用，直到重新发布此连接器：Copilot Studio 需要其 HTTP 模式，而此版本的该模式会检查令牌，但尚未设置请求大小或时间限制。请参阅 mcp-install.md 中的安全说明。
Google Gemini	Gemini CLI 是本地的——与 Claude Code 相同。Gemini app 是远程的，需要与 ChatGPT 相同的已暂停 HTTP 模式。请参阅 mcp-install.md。

原生支持 Skill 的 Agent（也有相关说明）：Hermes 和 OpenClaw 可直接读取此 Skill 的 SKILL.md，并且支持 MCP——请参阅下方对应的安装章节。Cursor、Windsurf、Cline、Continue.dev 和 Zed 也可通过 MCP 使用。各工具的完整接入说明：docs/which-agent.md。

**要运行多个 Agent？**只需一条命令，即可安装到全部 51+ 个受支持的 Agent：npx skills add Servosity/msp-skills@latest（需要 Node.js，然后运行每个 Skill 的安装程序以安装 CLI/MCP 二进制文件）。请参阅 docs/which-agent.md。

60 秒内完成安装

路径 A - 将一条提示词粘贴到 AI Agent 中（推荐）

将以下内容复制到 Claude Code、Codex CLI 或 Claude Cowork 中：

在此 Agent 工作区中安装 Servosity/msp-skills 的 HubSpot Skill 和 MCP 服务。如果此工作区使用 POSIX shell（macOS、Linux、WSL 或 Bash），请运行 bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/hubspot/install.sh)。如果使用 Windows PowerShell，请运行 iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/hubspot/install.ps1 | iex。然后按照 README 进行身份验证，并运行 hubspot-cli --help 以了解用法。

这条提示词适用于任何可以运行 shell 的 Agent。

路径 B - 自行运行安装程序

Windows（PowerShell）：

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/hubspot/install.ps1 | iex

macOS / Linux：

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/hubspot/install.sh)

安装程序会将 hubspot-cli（CLI）和 hubspot-mcp（MCP 服务）安装到用户的 bin 路径中。Claude Code、Codex 和 Cowork 会通过此目录中的 SKILL.md 发现该 Skill。

验证：

hubspot-cli --version

添加到 Claude Desktop、GitHub Copilot、Gemini CLI、Microsoft 365 Copilot 或其他 MCP 客户端

安装程序运行后，请参阅 mcp-install.md 和 docs/which-agent.md，了解各 Agent 的接入方法——每个 Agent 都有单独的章节，其中包括 GitHub Copilot 的 servers 键，以及远程 Microsoft 365 Copilot / Copilot Studio 路径。最简单的方法是使用 Claude Desktop 的 Settings > Extensions 面板；mcp-install.md 中也介绍了 MCP 配置块，供偏好编辑 JSON 的用户参考。

为 Hermes 安装

在 Hermes CLI 中：

hermes skills install servosity/msp-skills/skills/hubspot --force

在 Hermes 聊天会话中：

/skills install servosity/msp-skills/skills/hubspot --force

Hermes 原生支持 MCP，因此也可以直接使用 hubspot-mcp 服务——安装路径和环境变量均相同。

为 OpenClaw 安装

告诉你的 OpenClaw Agent（复制以下内容）：

从 https://github.com/servosity/msp-skills/tree/main/skills/hubspot 安装 hubspot skill。此 Skill 通过 openclaw: frontmatter 块定义其必需的 CLI（hubspot-cli）的安装方法。

OpenClaw 目前尚未全面开放；frontmatter 接线已预先提供，待 OpenClaw 发布后即可启用。

身份验证

设置 CLI 所需的凭据（从你的 HubSpot 门户获取）：

HUBSPOT_ACCESS_TOKEN=<value> hubspot-cli doctor

运行任何会操作数据的命令前，doctor 会确认凭据是否有效。即使凭据被拒绝，它仍会以 0 退出，因此脚本应添加 --fail-on error。

此技能的功能

MSP 经常问的问题	命令
本月哪些会议曾经处于「已安排」状态——即使后来变成了「未出席」或「已完成」？	hubspot-cli meetings status-report --status scheduled --month 2026-04
我今天该联系谁？（每日培育名单）	hubspot-cli nurture queue --owner me --top 20 --agent
哪些联系人或交易已经失去热度？	hubspot-cli stale contacts --days 30 --owner me
目前我的销售管道健康状况如何？（风险金额 + 停滞时间最长的交易）	hubspot-cli pipeline-health default --idle-days 14
我的销售代表是否负荷过重？	hubspot-cli owner-load --pipeline default
这笔交易的跨对象时间线是什么？（所有通话 + 邮件 + 会议 + 备注 + 任务）	hubspot-cli engagements of deal:1234567 --since 90d
从昨天以来，联系人、交易、互动和公司有哪些变化？	hubspot-cli since 24h

完整命令参考：guide.md。AI Agent 操作规范（--agent、--dry-run，以及何时在修改数据前确认）请参阅 AGENTS.md。

有何不同

大多数 HubSpot 集成和 MCP 服务都会将每个问题转发为实时 API 调用。查询单条记录时，这样做没问题。但如果问题变成「上个季度所有曾处于阶段 X 的交易——覆盖全部 200 个活跃客户——按阶段概率加权的风险金额，以及当前销售代表的工作负荷」，这种方式就会失效。标准 HubSpot 搜索／筛选 API 在技术上无法回答其中「曾在某个时间点处于阶段 X」这一部分——只有属性历史端点能做到；而通过实时 REST API 链接交易、联系人、所有者、互动和属性快照，需要调用 50 次，AI 还得耗费上下文来处理。

此技能会将 HubSpot 同步到本地 SQLite 镜像，其中包含全文搜索，以及属性历史快照表（唯一会将 propertiesWithHistory 保存为可查询形式的 HubSpot CLI/MCP）。聚合类问题只需执行一次本地 SQL 联接：即时、离线完成，AI 看到的是答案，而不是原始数据。meetings status-report、pipeline-health 和 engagements of 等复合命令可联接交易 × 联系人 × 所有者 × 互动 × 各属性历史快照——无状态 API 封装器无法完成这类工作。

解决的问题

痛点： 每月客户报告。MSP 客户会问：「4 月有多少场会议曾安排给我们？」——但到了生成报告时，这些会议全都已变成「已完成」或「未出席」。HubSpot 界面无法回答「是否曾经安排过」；标准搜索／筛选 API 也不行；属性历史端点虽然可以，但没有公开的 HubSpot CLI 或 MCP 能以可查询的形式提供该功能。有关运营人员长期以来的需求，请参阅 HubSpot Community 上关于 V3 属性历史的讨论；有关工作流影响的说明，请参阅 r/hubspot 上关于属性历史保留的讨论。

此技能通过五条命令弥补了这一缺口，MSP 所有者只需在一条 AI 提示词中即可运行：

• hubspot-cli sync --resources hubspot-meetings-crm --with-history hs_meeting_outcome,hs_meeting_title,hubspot_owner_id - 捕获属性快照，为报告准备数据
• hubspot-cli meetings status-report --status scheduled --month 2026-04 --csv - 一条命令即可生成客户报告
• hubspot-cli meetings ever-had --property hs_meeting_outcome --value Scheduled --from 2026-04-01 --to 2026-04-30 - 使用相同数据进行临时查询
• hubspot-cli pipeline-health default --idle-days 14 - 完成 QBR 的其余部分：本期有哪些风险
• hubspot-cli engagements of deal:<id> --since 90d - 查看讨论中的任意特定交易的完整活动记录

更详细的说明请参阅 pain-point.md。

常见问题

这能与 ChatGPT 搭配使用吗？

当前版本不支持。ChatGPT（Plus、Pro、Team、Business、Enterprise 和 Education 计划；Free 计划尚未开放 Developer Mode）只能通过 HTTPS 连接到远程 MCP 服务，这意味着需要以 HTTP 模式运行 HubSpot MCP 服务。当前版本的 HTTP 模式会检查令牌，但尚无请求大小或时间限制，因此在重新发布连接器之前，请勿运行它或将其置于隧道之后；mcp-install.md 中的安全说明解释了原因。在此之前，请使用 Claude Desktop、Claude Code 或 Codex。

这能与 Codex、Cursor、Windsurf、Cline、Copilot 或 Gemini 搭配使用吗？

可以——它们都支持 MCP。跨工具安装命令见上方的对照表，详细说明见 docs/which-agent.md。

我需要懂编程吗？

不需要。推荐的安装方式是在 Claude Code 或 Codex 中粘贴一句话——你的 Agent 会读取 SKILL.md 并完成安装。备用方式是针对各操作系统的一行安装命令（bash 或 PowerShell）。这两种方式都不需要编写代码。你只需输入一次 HubSpot 凭据。

我的 HubSpot 数据安全吗？

你的数据保留在自己的机器上。CLI 和 MCP 服务都是本地二进制文件。SQLite 镜像位于用户帐户下的目录中。AI Agent 只能看到 CLI 返回的内容——通常是查询结果，而不是原始批量数据。凭据从环境或 Agent 配置中读取；MSP Skills 绝不会将其打包进此仓库或传输到任何地方。

这与 HubSpot 自家的 Agent CLI（2026 年 5 月公布）有何不同？

HubSpot 于 2026-05-27 公布了自家的 Agent CLI——一个无状态、实时调用 API 的 CLI，用于定时 GTM 自动化（CRUD、JSONL、安全门控的批量操作）。这个技能是一个有状态、离线优先的配套工具：它能实现 HubSpot CLI 做不到的功能——本地 SQLite 镜像、全文搜索、通过一条命令跨对象联接，以及属性历史功能（meetings ever-had、meetings status-report），这些功能 HubSpot CLI 并未提供。在重要之处与其用法兼容（--filter 语法、JSONL 标准输入/输出，以及大批次操作中 contacts bulk-update 的 dry-run → digest → confirm 流程），因此为 HubSpot CLI 编写的提示词大多可以直接移用。

这会触发我的 HubSpot API 速率限制吗？

本地镜像的目的就是避免读取查询调用 API。首次运行 sync 后（该操作支持分页并会考虑速率限制——--with-history 会请求 propertiesWithHistory，根据 HubSpot 的批量读取 API 文档，每次请求返回的记录数有上限，因此 CLI 会相应分页），之后所有汇总报告都会在本地 SQLite 上运行——不会调用 API。同步操作本身很温和：内置分页，你可以用 --resources 和 --since 7d 限定范围；HubSpot 限流时，CLI 会发出同步警告事件，而不是悄悄忽略。

我需要成为 HubSpot 合作伙伴或购买特定套餐吗？

不需要成为合作伙伴。你需要一个 HubSpot Private App 访问令牌（可在任意门户中通过 app.hubspot.com/private-apps 免费创建），并为你关心的对象授予读取权限范围（联系人、交易、会议等）。属性历史的保留期限因套餐而异——HubSpot 在免费版/Starter 中保留约 90 天，在付费套餐中保留更久；CLI 会捕获响应中包含的所有内容，并从你首次使用 --with-history 同步时开始累积历史。

这会取代我的 HubSpot 界面吗？

不会。HubSpot 界面非常适合一次查看一条记录、编辑交易、拖放调整销售管道，以及处理销售代表每天都会用到的事务。这个技能面向的是销售代表和 AI Agent 无法从界面快速回答的汇总问题：“本周 200 笔交易有哪些变化”“本季度谁有风险”“4 月所有曾被安排的会议，即便后来状态发生了变化”。使用不同界面，处理的是同一份数据。

费用是多少？

免费。采用 Apache-2.0 许可证。你只需为使用的 AI Agent（Claude、ChatGPT、Codex 等）付费，费用由你的 AI 服务提供商收取，而不是我们。

安全模型

先了解真实情况：默认情况下，写操作不会受到限制。 --dry-run 是一个可选的全局标志（“发送前显示请求”，默认关闭）——如果 Agent 没有先传入 --dry-run，原始的创建、更新或删除命令会在首次运行时立即发送。内置的唯一变更操作门控位于 contacts bulk-update，且仅在超过 100 行时触发（较小的批次会立即发送，并显示一行绕过警告）。因此，真正的控制措施是你设置的 Agent 级策略，以及你授予令牌的权限范围。

层级	示例	推荐的 Agent 策略
读取	所有报告、汇总和搜索（stale、pipeline-health、nurture queue、deals top、engagements of、meetings history、meetings ever-had、meetings status-report、since、notes signals、owner-load、nurture-mine、history）	允许
写入（常规）	contacts bulk-update（摘要 + --confirm 门控，但仅适用于超过 100 行的情况——较小的批次会立即发送），crm post-…-batch-create/update/upsert（共 88 个；这些原始写操作没有 --confirm 标志，会立即发送）	让 Agent 传入 --dry-run 进行预览，然后在发送前要求人工批准确切的命令。小批次不要依赖内置门控。
凭据 / 安全	（未检测到）	仅限人工参与
破坏性操作	crm delete-…-archive、*-crm delete-…、hubspot-contacts-crm post-…-gdpr-delete（共 24 个）	仅限人工参与，并要求明确确认
管理员	（未检测到）	仅限操作员，不适用于 Agent

最有力的控制措施是授予 HubSpot 凭据的权限范围——CLI 只能执行凭据允许的操作。读取或报告工作流应使用只读令牌。有关完整详情（包括如何限制权限），请参阅 governance.md。

状态

已在线验证。由维护者 Servosity 在其生产租户上确认。还有更多 MSP 在我们的每周 Build Sessions 中实际运行该工具。请在 compoundingteams.com/build-sessions 报名。

---

标准。 符合开放的 Agent Skills 规范（Anthropic，2025 年 12 月；支持 40 多种 Agent）。兼容 MCP——可与任何支持 MCP 的 Agent 配合使用，包括 Hermes。已做好适配 OpenClaw 的准备（frontmatter 已预先配置，等待 OpenClaw 发布）。

由 Servosity 维护。采用 Apache-2.0 许可证。使用 CLI Printing Press 构建。最后更新：2026-06-04。