HubSpot MCP Server

HubSpot MCP 服务

用于 HubSpot API 的 MCP 服务，可让 Claude 与 HubSpot CRM 交互，进行销售分析并获取洞察。

免责声明

此开源项目与 HubSpot 无关联，也未获得其认可。这是一个独立实现，通过 HubSpot API 进行交互。

工具

核心 CRM 工具

1. hubspot_search_contacts

   • 使用查询字符串搜索 HubSpot 中的联系人
   • 必填输入：
     • query（字符串）：搜索查询字符串（电子邮箱、姓名等）
   • 可选输入：
     • count（数字，默认值：10）：返回的联系人数量上限
     • propertyList（数组）：要包含在结果中的属性列表
   • 返回：匹配联系人的列表及其属性

2. hubspot_get_contact

   • 按 ID 获取特定联系人
   • 必填输入：
     • contactId（字符串）：要获取的联系人 ID
   • 可选输入：
     • properties（数组）：要包含在结果中的属性列表
   • 返回：包含指定属性的联系人详情

3. hubspot_create_contact

   • 在 HubSpot 中创建新联系人
   • 必填输入：
     • properties（对象）：联系人属性，至少包含 email 字段
   • 返回：已创建的联系人详情

4. hubspot_update_contact

   • 更新 HubSpot 中的现有联系人
   • 必填输入：
     • contactId（字符串）：要更新的联系人 ID
     • properties（对象）：要更新的联系人属性
   • 返回：联系人已更新的确认信息

5. hubspot_list_deals

   • 分页列出 HubSpot 中的交易
   • 可选输入：
     • limit（数字，默认值：10，最大值：100）：返回的交易数量上限
     • after（字符串）：下一页的分页游标
     • properties（数组）：要包含在结果中的属性列表
   • 返回：交易列表及其详情

6. hubspot_get_deal

   • 按 ID 获取特定交易
   • 必填输入：
     • dealId（字符串）：要获取的交易 ID
   • 可选输入：
     • properties（数组）：要包含在结果中的属性列表
   • 返回：包含指定属性的交易详情

7. hubspot_create_deal

   • 在 HubSpot 中创建新交易
   • 必填输入：
     • properties（对象）：交易属性，至少包含 dealname 字段
   • 返回：已创建的交易详情

8. hubspot_update_deal

   • 更新 HubSpot 中的现有交易
   • 必填输入：
     • dealId（字符串）：要更新的交易 ID
     • properties（对象）：要更新的交易属性
   • 返回：交易已更新的确认信息

9. hubspot_list_companies

   • 分页列出 HubSpot 中的公司
   • 可选输入：
     • limit（数字，默认值：10，最大值：100）：返回的公司数量上限
     • after（字符串）：下一页的分页游标
     • properties（数组）：要包含在结果中的属性列表
   • 返回：公司列表及其详情

10. hubspot_get_company

    • 按 ID 获取特定公司
    • 必填输入：
      • companyId（字符串）：要获取的公司 ID
    • 可选输入：
      • properties（数组）：要包含在结果中的属性列表
    • 返回：包含指定属性的公司详情

销售分析工具

11. hubspot_get_sales_analytics

    • 获取特定时间段内汇总的销售分析数据
    • 必填输入：
      • period (string)：对分析数据进行分组的时间段（日、周、月、季度、年）
      • startDate (string)：分析的开始日期，采用 ISO 格式（YYYY-MM-DD）
    • 可选输入：
      • endDate (string)：分析的结束日期，采用 ISO 格式
      • pipeline (string)：用于筛选的销售管道 ID
      • dealStage (string)：用于筛选的交易阶段 ID
      • dealOwner (string)：用于筛选的交易所有者 ID
    • 返回：按时间段分组的汇总销售指标

12. hubspot_get_deal_history

    • 获取交易变更的完整历史记录
    • 必填输入：
      • dealId (string)：要获取历史记录的交易 ID
    • 返回：交易变更历史记录，包含时间戳和已修改的属性

13. hubspot_get_deal_notes

    • 获取与特定交易关联的备注
    • 必填输入：
      • dealId (string)：要获取备注的交易 ID
    • 可选输入：
      • limit (number, default: 20)：返回的备注数量上限
      • after (string)：下一页结果的分页游标
    • 返回：备注列表，包含备注内容和创建时间戳

14. hubspot_get_engagements_by_deal

    • 获取与交易关联的所有互动活动
    • 必填输入：
      • dealId (string)：要获取互动活动的交易 ID
    • 可选输入：
      • types (array)：要包含的互动活动类型（CALL、EMAIL、MEETING、TASK、NOTE）
      • limit (number, default: 20)：返回的互动活动数量上限
      • after (string)：下一页结果的分页游标
    • 返回：互动活动列表，包含详细信息和类型信息

15. hubspot_get_sales_performance

    • 获取特定时间段内销售代表的绩效指标
    • 必填输入：
      • period (string)：对绩效数据进行分组的时间段（日、周、月、季度、年）
      • startDate (string)：分析的开始日期，采用 ISO 格式（YYYY-MM-DD）
    • 可选输入：
      • endDate (string)：分析的结束日期，采用 ISO 格式
      • ownerIds (array)：要纳入分析的所有者 ID 列表
      • pipeline (string)：用于筛选的销售管道 ID
    • 返回：各销售代表的绩效指标，包括交易数量、收入和赢单率

16. hubspot_get_pipeline_analytics

    • 获取特定销售管道的分析数据，包括各阶段之间的转化率
    • 必填输入：
      • pipelineId (string)：要分析的销售管道 ID
      • period (string)：对分析数据进行分组的时间段（日、周、月、季度、年）
      • startDate (string)：分析的开始日期，采用 ISO 格式（YYYY-MM-DD）
    • 可选输入：
      • endDate (string)：分析的结束日期，采用 ISO 格式
    • 返回：销售管道阶段指标，包括交易数量、金额、转化率和阶段停留时间

17. hubspot_get_forecast_analytics

    • 根据当前销售管道和历史绩效获取销售预测数据
    • 必填输入：
      • period (string)：对预测数据进行分组的时间段（月、季度、年）
    • 可选输入：
      • numberOfPeriods (number, default: 3)：要预测的未来时间段数量
      • pipeline (string)：用于筛选的销售管道 ID
    • 返回：根据历史数据和当前销售管道得出的未来时间段销售预测指标

设置

1. 创建 HubSpot 私有应用：

   • 前往你的 HubSpot 账户
   • 导航至“设置” → “账户设置” → “集成” → “私有应用”
   • 点击“创建私有应用”
   • 为应用命名并设置适当的权限范围（联系人、交易和公司）
   • 创建应用并复制私有应用令牌

2. 所需权限范围：

   • crm.objects.contacts.read
   • crm.objects.contacts.write
   • crm.objects.deals.read
   • crm.objects.deals.write
   • crm.objects.companies.read
   • crm.objects.companies.write
   • crm.objects.owners.read
   • crm.objects.quotes.read
   • crm.objects.line_items.read
   • crm.objects.custom.read
   • crm.schemas.deals.read
   • crm.schemas.contacts.read
   • crm.schemas.companies.read
   • crm.schemas.custom.read

在 Claude Desktop 中使用

将以下内容添加到你的 claude_desktop_config.json：

npx

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

docker

{
  "mcpServers": {
    "hubspot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HUBSPOT_API_KEY", "mcp/hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

故障排除

如果遇到错误，请确认：

1. 已将所有必需的权限范围添加到 HubSpot 私有应用
2. 已将 API 密钥正确复制到配置中
3. 你的 HubSpot 套餐包含你尝试使用的 API 的访问权限

构建

Docker 构建：

docker build -t mcp/hubspot -f Dockerfile .

许可证

此 MCP 服务采用 MIT 许可证。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目代码库中的 LICENSE 文件。