Connect HubSpot MCP 用于把 Claude Code 连接到 HubSpot 官方远程 MCP 服务器，让 Claude 能以对话方式读取和写入 CRM 记录，例如查询联系人、查看某公司的交易、抽查清理结果，而无需为每个问题单独编写脚本。
用途与定位
HubSpot 远程 MCP 服务器（自 2026 年 4 月起正式可用）是位于 mcp.hubspot.com 的 OAuth 安全网关，将 CRM 操作作为工具暴露给 Claude Code 等 MCP 客户端。它适合交互式、依赖判断的工作：抽查、分诊、一次性查询、小范围定向修改。它不适合批量操作：批量归档数千个联系人、分页扫描，或任何需要 CSV 审计轨迹和中止阈值的任务。后者应使用该仓库中的脚本。两者共享同一门户，可以配合使用。
任务形态与工具选择
- “显示清理操作涉及的 5 个联系人”：使用 MCP
- “这家公司为什么属于 Tier 2？”：使用 MCP
- “查看本周被标记为退信的联系人”：使用 MCP
- “删除 4,000 个无邮箱联系人并保留审计轨迹”：使用脚本（/delete-no-email-contacts）
- “创建 10 个细分列表”：使用脚本（/build-smart-lists）
- “将所有工作流导出为 JSON”：使用脚本（/workflows-as-code）
主要能力
MCP 服务器可读写 CRM 对象：联系人、公司、交易、工单、行项目、产品、互动记录；可读取内容：营销活动、落地页、网站页面、博客文章和内容分析；可创建内容：落地页（2026 年 6 月新增）。
前置条件
需要一个 HubSpot 账户，以及有权创建用户级应用的用户（或通过门户的 MCP Auth Apps 治理获得批准，若已启用）。需要 Claude Code 或其他 MCP 客户端。这与脚本使用的私有应用令牌相互独立——MCP 以你的身份通过 OAuth 连接，并继承你的 HubSpot 权限。
执行流程
阶段一：规划。决定授予的权限范围，先只读（CRM 对象读取范围），仅在希望 Claude 通过 MCP 进行修改时才添加写入范围。与管理员确认门户是否限制应用安装（App Install Governance），MCP 连接可能需要审批。
阶段二：执行——连接。
选项 A：HubSpot Connector for Claude（无需终端）。在 Claude 的连接器设置中添加 HubSpot 连接器，并在浏览器中完成 OAuth 流程。HubSpot 指南见 knowledge.hubspot.com 的“Set up and use the HubSpot connector for Claude”。
选项 B：MCP 客户端配置。将远程服务器添加到 Claude Code：
claude mcp add --transport http hubspot https://mcp.hubspot.com
然后在提示时进行身份验证——OAuth 流程会创建一个用户级应用，并包含你批准的权限范围。
选项 C：HubSpot CLI。使用 HubSpot CLI v8.2.0+，hs mcp setup 会引导连接 MCP 客户端，同时提供 HubSpot 本地开发者 MCP 服务器（面向应用开发而非 CRM 管理）。
阶段三：之后——验证。让 Claude 执行一次无害读取并确认往返成功：
“使用 HubSpot MCP 工具获取一个联系人，并告诉我其邮箱和生命周期阶段。”
如果调用失败：检查 OAuth 流程是否完成、权限范围是否包含联系人读取、门户是否通过应用治理阻止了连接。
回滚
从客户端设置中断开 MCP 服务器（在 Claude Code 中执行 claude mcp remove hubspot）。在 HubSpot 中撤销连接：Settings > Integrations > Connected Apps——移除用户级应用会使其令牌失效。
技术注意事项
MCP 访问以用户为范围。Claude 能做的恰好是你的 HubSpot 用户能做的，不多不少。批量风险操作自然受所授予权限范围的限制；请谨慎授予写入范围。
两套凭据，两种用途。HUBSPOT_ACCESS_TOKEN（私有应用）驱动脚本；MCP OAuth 连接驱动对话式访问。轮换其中一个不影响另一个。
速率限制仍然适用。MCP 调用消耗与任何集成相同的 API 容量。不要用 MCP 进行高容量扫描——那属于脚本的领域。
无头环境。需要交互式 OAuth 的 MCP 服务器在计划任务/CI 运行中可能不可用。使用私有应用令牌的脚本在任何环境都能工作；应将 MCP 视为交互层。