HubSpot MCP Server

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 (字符串)：按时间周期分组分析数据的时间周期（每日、每周、每月、每季度、每年）
      • startDate (字符串)：用于分析的起始日期，ISO 格式（YYYY-MM-DD）
    • 可选输入：
      • endDate (字符串)：用于分析的结束日期，ISO 格式
      • pipeline (字符串)：过滤用的流水线 ID
      • dealStage (字符串)：过滤用的交易阶段 ID
      • dealOwner (字符串)：过滤用的交易所有者 ID
    • 返回：按时间周期分组的聚合销售指标

12. hubspot_get_deal_history

    • 获取交易的所有变更历史
    • 必需输入：
      • dealId (字符串)：要获取历史记录的交易的 ID
    • 返回：带有时间戳和修改属性的交易变更历史

13. hubspot_get_deal_notes

    • 获取与特定交易相关的笔记
    • 必需输入：
      • dealId (字符串)：要获取笔记的交易的 ID
    • 可选输入：
      • limit (数字，默认值：20)：返回的最大笔记数
      • after (字符串)：下一页结果的分页游标
    • 返回：带有内容和创建时间戳的笔记列表

14. hubspot_get_engagements_by_deal

    • 获取与交易相关的所有互动活动
    • 必需输入：
      • dealId (字符串)：要获取互动的交易的 ID
    • 可选输入：
      • types (数组)：要包含的互动类型（CALL, EMAIL, MEETING, TASK, NOTE）
      • limit (数字，默认值：20)：返回的最大互动数
      • after (字符串)：下一页结果的分页游标
    • 返回：带有详细信息和类型信息的互动列表

15. hubspot_get_sales_performance

    • 获取销售人员在特定时间段内的绩效指标
    • 必需输入：
      • period (字符串)：按时间周期分组绩效数据的时间周期（每日、每周、每月、每季度、每年）
      • startDate (字符串)：用于分析的起始日期，ISO 格式（YYYY-MM-DD）
    • 可选输入：
      • endDate (字符串)：用于分析的结束日期，ISO 格式
      • ownerIds (数组)：要包含在分析中的所有者 ID 列表
      • pipeline (字符串)：过滤用的流水线 ID
    • 返回：每个销售人员的绩效指标，包括交易数量、收入和胜率

16. hubspot_get_pipeline_analytics

    • 获取特定销售流水线的分析，包括各阶段之间的转化率
    • 必需输入：
      • pipelineId (字符串)：要分析的流水线的 ID
      • period (字符串)：按时间周期分组分析数据的时间周期（每日、每周、每月、每季度、每年）
      • startDate (字符串)：用于分析的起始日期，ISO 格式（YYYY-MM-DD）
    • 可选输入：
      • endDate (字符串)：用于分析的结束日期，ISO 格式
    • 返回：流水线阶段指标，包括交易数量、价值、转化率和阶段停留时间

17. hubspot_get_forecast_analytics

    • 基于当前流水线和历史表现预测未来的销售数据
    • 必需输入：
      • period (字符串)：按时间周期分组预测数据的时间周期（每月、每季度、每年）
    • 可选输入：
      • numberOfPeriods (数字，默认值：3)：要预测的未来周期数
      • pipeline (字符串)：过滤用的流水线 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 文件。 </中文翻译>