HubSpot

@mindstone/mcp-server-hubspot

用于 CRM 操作（联系人、公司、交易、工单、潜在客户、任务、备注、关联）、属性和所有者、营销/列表、工作流、知识库查询及文件操作的 HubSpot MCP 服务。

支持多账户的 HubSpot MCP，采用由宿主协调的 OAuth、沙盒化文件上传，并为每条新记录添加来源归属标签。

状态

• 版本： 0.4.1 · npm
• 身份验证： OAuth（由宿主协调）(HUBSPOT_CLIENT_SECRET)
• 工具： 106（CRM 对象、关联、营销、文件、工作流、对话）
• 接口： cloud-api
• 机器可读： STATUS.json

为什么开发此项目

HubSpot 发布了官方 HTTP MCP 服务（于 2026 年初宣布进入公开测试阶段），社区中也有多个 HubSpot MCP 项目。开发此连接器时，我们需要的是不同的方案：仅在用户机器上运行的本地服务，可同时支持多个 HubSpot 账户，将每个账户的凭据保存在单独的文件中，为新记录添加标签，方便用户识别由 AI Agent 创建的内容，并将文件上传限制在磁盘上的单个工作区文件夹内。现有方案都无法满足这些需求，因此我们自行开发了此项目，并进行了自己的安全审查。

交互示例

“在 HubSpot 中查找 Acme Corp，记录一条备注，说明我们和他们的 CTO 通话很愉快，并安排在下周二跟进。”

宿主调用的工具：

1. search_hubspot_companies — 按名称查找 Acme Corp 并返回其公司 ID。
2. create_hubspot_note — 在公司记录上添加备注。
3. create_hubspot_task — 安排一项截止日期为下周二的跟进任务，并将其关联到该公司。

响应（已删节）：

{
  "company": { "id": "12345678901", "name": "Acme Corp" },
  "note": {
    "id": "9876543210",
    "createdAt": "2026-05-19T14:02:11Z",
    "body": "Great call with CTO — discussed Q3 rollout."
  },
  "task": {
    "id": "5566778899",
    "subject": "Follow up with Acme Corp",
    "dueDate": "2026-05-26T16:00:00Z"
  }
}

要求

• Node.js 20+
• npm
• 可执行 HubSpot OAuth 流程并将每个账户的凭据写入 ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json 的宿主应用。此服务会读取这些文件；它不会运行本地 OAuth 回调。
• 如果要使用文件上传工具，需要一个可写入的 MCP_WORKSPACE_PATH 目录。

一键安装

点击按钮后，宿主将提示你填写：HUBSPOT_CONFIG_DIR、HUBSPOT_ACCOUNT_EMAIL、HUBSPOT_CLIENT_ID、HUBSPOT_CLIENT_SECRET、HUBSPOT_SOURCE_LABEL、HUBSPOT_REQUEST_TIMEOUT_MS。

{
  "mcpServers": {
    "HubSpot": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-hubspot"
      ],
      "env": {
        "HUBSPOT_CONFIG_DIR": "",
        "HUBSPOT_ACCOUNT_EMAIL": "",
        "HUBSPOT_CLIENT_ID": "",
        "HUBSPOT_CLIENT_SECRET": "",
        "HUBSPOT_SOURCE_LABEL": "HubSpot MCP",
        "HUBSPOT_REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

快速开始

安装与构建

cd <path-to-repo>/connectors/hubspot
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-hubspot

本地

node dist/index.js

配置

此服务专为由宿主编排的 OAuth 而设计。它会从磁盘读取由宿主管理的凭据。

必需的环境变量

• HUBSPOT_CONFIG_DIR — 包含 accounts.json 和 credentials/*.token.json 的配置目录。
• HUBSPOT_ACCOUNT_EMAIL — 此进程的账户选择器（每个 HubSpot 账户对应一个 MCP 进程）。
• MCP_WORKSPACE_PATH — 本地文件工具（upload_hubspot_file、attach_file_to_record）使用的工作区根目录。

OAuth 桥接变量（由宿主注入）

• HUBSPOT_CLIENT_ID
• HUBSPOT_CLIENT_SECRET
• HUBSPOT_SOURCE_LABEL（可选）— 覆盖新记录上使用的来源归属标签（默认值：HubSpot MCP）

即使未设置这些值，服务仍会启动（未配置模式），但需要经过身份验证才能访问 HubSpot API 的工具会返回结构化的 auth_required 响应。

身份验证流程

authenticate_hubspot_account 会返回结构化的 auth_required 响应：

{
  "status": "auth_required",
  "user_action": { "id": "hubspot.connect_account" },
  "agent_action": {
    "instruction": "Tell the user that HubSpot needs reauthentication. The host will open the OAuth flow in their browser; once complete, retry the original request."
  },
  "setupToolName": "authenticate_hubspot_account"
}

宿主会识别此结构并启动浏览器 OAuth 流程。

宿主配置示例

此服务专为由宿主编排的 OAuth 而设计：宿主会将每个账户的凭据文件写入磁盘，服务则从中读取。以下示例展示了环境变量的格式 — 宿主应用负责在工具调用成功前填充 ${HUBSPOT_CONFIG_DIR}/credentials/*.token.json。

Claude Desktop / Cursor

{
  "mcpServers": {
    "HubSpot": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-hubspot"],
      "env": {
        "HUBSPOT_CONFIG_DIR": "/absolute/path/to/hubspot-config",
        "HUBSPOT_ACCOUNT_EMAIL": "[email protected]",
        "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace",
        "HUBSPOT_CLIENT_ID": "your-hubspot-app-client-id",
        "HUBSPOT_CLIENT_SECRET": "your-hubspot-app-client-secret"
      }
    }
  }
}

在宿主写入 ${HUBSPOT_CONFIG_DIR}/credentials/[email protected] 之前，需要经过身份验证才能访问 HubSpot 的工具会返回结构化的 auth_required 响应（参见上文的身份验证流程）。

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "HubSpot": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/hubspot/dist/index.js"],
      "env": {
        "HUBSPOT_CONFIG_DIR": "/absolute/path/to/hubspot-config",
        "HUBSPOT_ACCOUNT_EMAIL": "[email protected]",
        "MCP_WORKSPACE_PATH": "/absolute/path/to/workspace",
        "HUBSPOT_CLIENT_ID": "your-hubspot-app-client-id",
        "HUBSPOT_CLIENT_SECRET": "your-hubspot-app-client-secret"
      }
    }
  }
}

工具（106）

账户与身份验证

• list_hubspot_accounts — 列出已连接的 HubSpot 账户及其身份验证状态。
• authenticate_hubspot_account — 启动 OAuth 流程以连接 HubSpot 账户。
• complete_hubspot_auth — 等待 OAuth 回调并持久化凭据。
• remove_hubspot_account — 断开 HubSpot 账户连接并删除已存储的凭据（破坏性操作）。

联系人

• search_hubspot_contacts — 按查询条件或属性筛选条件搜索联系人。
• get_hubspot_contact — 按 ID 获取单个联系人。
• create_hubspot_contact — 创建联系人（破坏性操作）。
• update_hubspot_contact — 更新联系人属性（破坏性操作）。
• delete_hubspot_contact — 永久删除联系人（破坏性操作）。

公司

• search_hubspot_companies — 按查询条件或属性筛选条件搜索公司。
• get_hubspot_company — 按 ID 获取单个公司。
• create_hubspot_company — 创建公司（破坏性操作）。
• update_hubspot_company — 更新公司属性（破坏性操作）。
• delete_hubspot_company — 永久删除公司（破坏性操作）。

交易

• search_hubspot_deals — 按查询条件或属性筛选条件搜索交易。如需完整覆盖，请使用 paging.next.after 中的 after 重复查询，直到不再返回下一个游标。
• get_hubspot_deal — 按 ID 获取单笔交易。
• create_hubspot_deal — 创建交易；需要 hubspot_owner_id（破坏性操作）。
• update_hubspot_deal — 更新交易属性或变更阶段（破坏性操作）。
• delete_hubspot_deal — 永久删除交易（破坏性操作）。

工单

• search_hubspot_tickets — 使用筛选条件搜索工单。
• get_hubspot_ticket — 按 ID 获取单个工单。
• create_hubspot_ticket — 创建支持工单（破坏性操作）。
• update_hubspot_ticket — 更新工单属性（破坏性操作）。
• delete_hubspot_ticket — 删除工单（破坏性操作）。

潜在客户（Sales Hub Pro/Enterprise）

• search_hubspot_leads — 按查询条件或属性筛选条件搜索潜在客户。
• get_hubspot_lead — 按 ID 获取单个潜在客户。
• create_hubspot_lead — 创建关联到联系人的潜在客户（破坏性操作）。
• update_hubspot_lead — 更新潜在客户属性（破坏性操作）。
• delete_hubspot_lead — 永久删除潜在客户（破坏性操作）。

任务

• search_hubspot_tasks — 使用筛选条件搜索任务。
• get_hubspot_task — 按 ID 获取单个任务。
• create_hubspot_task — 创建任务（破坏性操作）。
• update_hubspot_task — 更新任务属性（破坏性操作）。
• delete_hubspot_task — 删除任务（破坏性操作）。

备注

• search_hubspot_notes — 按正文文本或属性筛选条件搜索备注。
• get_hubspot_note — 按 ID 获取单条备注。
• create_hubspot_note — 创建备注，并可选择将其关联到记录（破坏性操作）。
• update_hubspot_note — 更新备注属性，例如编辑正文（破坏性操作）。
• delete_hubspot_note — 永久删除备注（破坏性操作）。

自定义对象

• search_hubspot_object — 搜索任意对象类型的记录，包括租户定义的自定义对象（原生全文查询）。
• get_hubspot_object — 按 ID 获取任意对象类型的单条记录。
• create_hubspot_object — 创建任意对象类型的记录（破坏性操作）。自定义对象需要 crm.objects.custom.write 范围。

关联

• create_hubspot_association — 在两条记录之间创建无标签关联（v3）（破坏性操作）。
• get_hubspot_associations — 列出某条记录的指定类型关联。
• delete_hubspot_association — 移除两条记录之间的关联（破坏性操作）。
• list_hubspot_association_labels — 列出两种对象类型之间可用的关联标签（v4）。
• create_hubspot_labeled_association — 在两条记录之间创建带标签的关联（v4）（破坏性操作）。

属性与架构

• list_hubspot_properties — 列出某种对象类型的属性定义。
• get_hubspot_property — 获取单个属性定义。
• create_hubspot_property — 在对象上创建自定义属性（具有破坏性）。
• update_hubspot_property — 更新现有属性定义（具有破坏性）。
• delete_hubspot_property — 将对象的属性归档（具有破坏性）。
• list_hubspot_property_groups — 列出某种对象类型的属性组。
• create_hubspot_property_group — 创建新的属性组（具有破坏性）。

所有者

• list_hubspot_owners — 列出可拥有 CRM 记录的 HubSpot 用户。
• get_hubspot_owner — 按 ID 获取特定所有者的详细信息。

管道

• list_hubspot_pipelines — 列出销售/工单管道及其阶段。
• get_hubspot_pipeline — 获取特定管道及其阶段。

互动记录（电话、会议和电子邮件）

• search_hubspot_calls — 按筛选条件搜索已记录的电话。
• search_hubspot_meetings — 按筛选条件搜索已记录的会议。
• search_hubspot_emails — 按筛选条件搜索已记录的一对一销售电子邮件（读取正文需要 sales-email-read 权限范围；notes 警告表示内容已删减，或权限范围检查无法验证）。
• get_hubspot_call — 按 ID 获取单条电话记录。
• get_hubspot_meeting — 按 ID 获取单条会议记录。
• get_hubspot_email — 按 ID 获取单条电子邮件互动记录。
• create_hubspot_call — 记录电话，并可选择将其关联到记录（具有破坏性）。
• create_hubspot_meeting — 记录会议，并可选择将其关联到记录（具有破坏性）。
• get_contact_engagements — 获取联系人的近期电话、电子邮件和会议记录。

产品

• search_hubspot_products — 搜索产品目录。
• get_hubspot_product — 按 ID 获取单个产品。
• create_hubspot_product — 在目录中创建产品（具有破坏性）。
• update_hubspot_product — 更新现有产品（具有破坏性）。

明细项

• search_hubspot_line_items — 按筛选条件搜索明细项。
• get_hubspot_line_item — 按 ID 获取单个明细项。
• create_hubspot_line_item — 创建明细项，并可选择将其关联到交易（具有破坏性）。

表单

• list_hubspot_forms — 列出 HubSpot 中的表单。
• get_hubspot_form — 获取表单的配置和字段。
• get_hubspot_form_submissions — 获取表单的提交记录。

分析（Marketing Hub Pro/Enterprise）

• get_hubspot_analytics_report — 获取网站流量分析报告。

营销电子邮件

• list_hubspot_marketing_emails — 列出营销电子邮件。
• get_hubspot_marketing_email — 获取营销电子邮件的详细信息。
• get_hubspot_email_statistics — 获取汇总的电子邮件效果统计数据。

列表与细分

• list_hubspot_lists — 列出联系人列表/细分。
• get_hubspot_list — 获取列表的详细信息和筛选条件。
• list_hubspot_list_members — 获取属于某个列表的联系人 ID。
• add_hubspot_list_members — 向 MANUAL/SNAPSHOT 列表添加记录（具有破坏性；需要 crm.lists.write）。
• remove_hubspot_list_members — 从 MANUAL/SNAPSHOT 列表移除记录（具有破坏性；需要 crm.lists.write）。
• batch_read_hubspot_contacts — 在一次请求中按 ID 获取最多 100 个联系人。

知识库（Service Hub Pro/Enterprise）

• list_hubspot_kb_articles — 列出知识库文章（GraphQL）。
• get_hubspot_kb_article — 按 ID 获取单篇知识库文章。
• search_hubspot_kb_articles — 通过站点搜索查找已发布的知识库文章。

文件

• upload_hubspot_file — 将本地文件上传到 HubSpot 文件管理器（有破坏性；需要 MCP_WORKSPACE_PATH）。
• import_hubspot_file_from_url — 从公开 URL 将文件导入文件管理器（有破坏性）。
• get_hubspot_file — 获取文件元数据；可选择返回可查看的签名 URL。
• delete_hubspot_file — 从文件管理器中删除文件（有破坏性）。
• attach_file_to_record — 上传或导入文件，并通过备注将其附加到记录（有破坏性；上传本地文件时需要 MCP_WORKSPACE_PATH）。

工作流（v4 BETA；Marketing Hub Pro/Enterprise）

• list_hubspot_workflows — 列出自动化工作流。
• get_hubspot_workflow — 获取工作流的操作、触发器和分支。
• create_hubspot_workflow — 创建新的工作流（有破坏性）。
• update_hubspot_workflow — 替换工作流配置（有破坏性）。
• delete_hubspot_workflow — 永久删除工作流（有破坏性）。
• activate_hubspot_workflow — 启用工作流（有破坏性）。
• deactivate_hubspot_workflow — 禁用工作流（有破坏性）。
• enrol_in_hubspot_workflow — 将指定记录加入工作流（有破坏性）。

安全说明

• 文件工具使用 MCP_WORKSPACE_PATH 和规范路径检查来确保路径位于工作区内。
• 本地凭据从主机管理的文件中读取；账号选择由 HUBSPOT_ACCOUNT_EMAIL 固定。
• 此服务不会运行本地 OAuth 回调服务；OAuth 由主机协调处理。
• 来源归属标签仅应用于新写入的内容。现有 HubSpot 记录内容绝不会被追溯改写。
• HubSpot 返回的所有文本（记录属性、备注/互动正文、对话消息、知识库文章、表单提交内容、名称/标签）都会包装在 <untrusted-content source="hubspot:…"> 信封中，并对闭合标签进行转义，使处理工具输出的模型将第三方编写的文本视为数据，而非指令。标识符、枚举值、URL、时间戳和分页游标保持原样，以确保工具往返处理正常；但记录的 properties 字段除外，其中的每个值都会被包装，无论属性名称为何（自定义属性名称由租户定义，因此不可信；记录 ID 通过顶层 id 往返）。各表面例外（属性架构中的 name/groupName/选项 value、表单字段绑定）仅适用于其文档所述的响应结构。
• 所有请求日志和错误摘要都会对 OAuth 访问令牌进行脱敏处理，包括路径由令牌本身指定的令牌信息端点。

许可

FSL-1.1-MIT — Functional Source License，Version 1.1，附带未来适用的 MIT 许可。该软件将于 2030-04-08 转为 MIT 许可。