HubSpot MCP Server (Official)已精选

什么是 HubSpot MCP Server (Official)？

HubSpot MCP 是 HubSpot 官方提供的远程 MCP 服务器，地址为 https://mcp.hubspot.com。它让 AI 助手通过自然语言读取 CRM 记录、活动、营销内容和会话，并在获得授权时进行更新，使用 OAuth 登录。

该服务器由 HubSpot 托管，无需在本地安装或运行任何程序。HubSpot 另外还提供一个独立的本地 Developer MCP server，用于借助 HubSpot CLI 构建应用和 CMS 内容，它不查询 CRM 数据。本页介绍的是远程 HubSpot MCP 服务器。

如何使用 HubSpot MCP Server (Official)？

前提条件： 一个 HubSpot 用户账号，以及支持 OAuth + PKCE（S256）的 MCP 客户端。无需 API key，访问权限通过 OAuth 流程获得。

方式一：内置连接器（Claude 应用）。 在 Claude（网页版、桌面版或移动版）中打开 Settings > Connectors，点击 Browse，搜索 HubSpot，点击 Connect，登录 HubSpot 账号，选择权限后点击 Connect app。此方式需要 Anthropic 付费套餐（Pro、Max、Team 或 Enterprise）。Super Admin 和拥有 App Marketplace Access 权限的用户可以直接连接；其他用户需要先由 Super Admin 批准该连接器。

方式二：任意 MCP 客户端 + 自建 MCP connector。

1. 在 HubSpot 中进入 Development > MCP Connectors（https://app.hubspot.com/l/mcp-auth-apps/），点击 Create MCP connector。
2. 填写名称和客户端使用的 redirect URL，然后点击 Create。
3. 在 connector 详情页复制 client ID 和 client secret。
4. 在客户端中配置 https://mcp.hubspot.com、client ID 和 secret，以及匹配的 redirect URL。
5. 完成 OAuth 流程（选择账号、授予权限、确认授权），然后让助手运行 get_user_details 以确认连接成功。

Claude Code

本页给出的快速命令：

claude mcp add hubspot --transport http https://mcp.hubspot.com

如果客户端需要 connector 的凭据，Claude Code 支持预配置的 OAuth 凭据。先在 connector 上登记 http://localhost:8080/callback 作为 redirect URL，然后运行：

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID --client-secret --callback-port 8080 \
  hubspot https://mcp.hubspot.com

--client-secret 会提示输入 secret。在 Claude Code 中运行 /mcp 即可登录。

Cursor

在 ~/.cursor/mcp.json（或项目的 .cursor/mcp.json）中添加远程服务器：

{
  "mcpServers": {
    "hubspot": {
      "url": "https://mcp.hubspot.com"
    }
  }
}

VS Code

在 .vscode/mcp.json 中添加服务器：

{
  "servers": {
    "hubspot": {
      "type": "http",
      "url": "https://mcp.hubspot.com"
    }
  }
}

在 Cursor 和 VS Code 中，如果客户端要求提供 OAuth 客户端凭据，请使用 MCP connector 的 client ID、secret 和匹配的 redirect URL。

如需用 MCP Inspector 测试，请选择 Streamable HTTP 传输并填写 https://mcp.hubspot.com/，同时把 http://localhost:6274/oauth/callback/debug 添加为 connector 的 redirect URL。

HubSpot MCP Server (Official) 的主要功能

• 官方托管： 由 HubSpot 在 https://mcp.hubspot.com 运行，使用 Streamable HTTP 传输，无需本地进程。
• OAuth + PKCE： 通过 HubSpot 登录，无需在配置文件中粘贴 token。
• 广泛的 CRM 读取权限： 联系人、公司、交易、工单、线索、用户、预约、项目、服务、自定义对象和 segment，以及通话、邮件、会议、备注和任务。
• 在权限允许时写入： 创建和编辑 CRM 记录、活动、pipeline、自定义属性和静态 segment；会遵守条件字段逻辑和 pipeline 阶段校验。
• 营销与内容： 营销活动、营销邮件草稿与分析、落地页、网站页面和博客文章。
• 会话： 在线聊天、团队邮箱、WhatsApp、SMS、Facebook Messenger 和自定义渠道，取决于收件箱配置。
• 遵循权限： 每个请求都以安装用户的身份执行，Super Admin 控制 connector 可访问的数据权限。

HubSpot MCP Server (Official) 工具

工具是否可用取决于订阅、权限和账号配置：

• 账号与架构： get_user_details、get_organization_details 和 discover_hubspot_schema 用于识别用户、portal 及其对象模型。
• CRM 记录： search_crm_objects（最多 5 个过滤组，每组 6 个过滤条件，每页 200 条结果）、get_crm_objects（每次最多 100 个 ID）、manage_crm_objects 和 manage_segment。
• 数据与属性： query_crm_data 用于结构化查询（需先调用 tool_guidance），以及 search_properties、get_properties、manage_custom_properties、manage_custom_pipelines 和 search_owners。
• 营销活动与营销： read_campaign_data、manage_campaign_objects、get_campaign_attribution_reports、get_marketing_email_analytics 和 manage_marketing_email。
• 内容： manage_landing_page、manage_website_page、manage_blog_post、render_asset 和 get_content_analytics_report。
• 会话与信号： search_conversations、get_conversation_channel_metadata 和 search_intent_signals。
• AEO： get_aeo_metrics、manage_aeo_prompts 和 manage_aeo_recommendations（需要 Marketing Hub Professional 或 Enterprise）。

部分写入工具（如 manage_crm_objects 和 manage_blog_post）在修改数据前会请求用户确认。

HubSpot MCP Server (Official) 的使用场景

• Pipeline 复盘： “汇总所有金额超过 5 万美元、最近 14 天没有任何活动的未结交易。”
• 通话前的客户调研： “拉取 Acme Corp 最新的备注、邮件和会议，并列出未关闭的工单。”
• CRM 数据清理： “找出 example.com 域名下没有负责人的联系人，并分配给我。”
• 记录工作： “记录今天与 Jane Doe 的一次通话，并创建下周二的跟进任务。”
• 营销分析： “上个月的营销邮件表现如何？”

HubSpot MCP Server (Official) 与替代方案对比

• HubSpot Developer MCP server（官方，本地）： 通过 HubSpot CLI 8.2.0+ 运行 hs mcp setup 安装，支持 Claude Code、Codex CLI、Cursor、Gemini CLI、VS Code 和 Windsurf。它用于构建应用和 CMS 资源，而不是查询 CRM 数据。
• 社区服务器： mcp-hubspot（Docker 部署，基于 FAISS 对已获取数据进行语义搜索）和 Shinzo Labs HubSpot MCP（npx 或 Smithery）使用 HubSpot access token 而不是 OAuth 进行认证。它们并非由 HubSpot 维护。

HubSpot MCP Server (Official) 常见问题排查

• OAuth redirect 报错： 客户端发送的 redirect URL 必须与 MCP connector 上登记的某个 URL 完全一致。列表中的第一个 redirect URL 为默认值。
• PKCE 或 token 报错： PKCE 是必需的。code_verifier 长度须为 43 到 128 个字符，challenge 必须使用 code_challenge_method=S256。如果 refresh token 已过期或失效，请重新执行完整的 OAuth 流程。
• 看不到新工具或新数据： scope 在安装时授予。HubSpot 新增工具或 Super Admin 修改权限后，需要重新安装或重新连接以授予新的 scope。
• 没有活动或会话数据： 如果账号启用了 Sensitive Data，MCP 服务器会屏蔽活动和会话数据。