HubSpot MCP Server

HubSpot MCP 服务

一个功能强大的 Model Context Protocol（MCP）服务实现，可无缝集成 HubSpot CRM，让 AI 助手能够与您的 HubSpot 数据交互。

概述

此 MCP 服务提供了一套全面的工具，用于与 HubSpot CRM API 交互，使 AI 助手能够：

• 在您的 HubSpot CRM 中创建和管理联系人及公司
• 获取详细的公司活动历史记录和互动时间线
• 访问整个 HubSpot 实例中的近期互动数据
• 获取近期活跃的公司和联系人列表
• 无需离开 AI 助手界面即可执行 CRM 操作

为什么使用此 MCP 服务？

• 无缝集成 AI：将 AI 助手直接连接到您的 HubSpot CRM 数据
• 简化 CRM 操作：通过自然语言命令执行常见的 HubSpot 任务
• 实时访问数据：从您的 HubSpot 实例获取最新信息
• 安全身份验证：使用 HubSpot 安全的 API 令牌身份验证
• 可扩展设计：可根据需要轻松添加更多 HubSpot API 功能

安装

# Clone the repository
git clone https://github.com/lkm1developer/hubspot-mcp-server.git
cd hubspot-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

配置

此服务需要 HubSpot API 访问令牌。您可以通过以下方式获取：

1. 前往您的 HubSpot Developer Account
2. 创建一个具有必要权限范围（contacts、companies、engagements）的私有应用
3. 复制生成的访问令牌

您可以通过两种方式提供令牌：

1. 作为环境变量：

   HUBSPOT_ACCESS_TOKEN=your-access-token
   

2. 作为命令行参数：

   npm start -- --access-token=your-access-token
   

在开发过程中，请在项目根目录下创建 .env 文件，以存储环境变量：

HUBSPOT_ACCESS_TOKEN=your-access-token

使用方法

启动服务

# Start the server
npm start

# Or with a specific access token
npm start -- --access-token=your-access-token

# Run the SSE server with authentication
npx mcp-proxy-auth node dist/index.js

在 SSE 服务中实现身份验证

SSE 服务使用 mcp-proxy-auth 包进行身份验证。实现身份验证的步骤如下：

1. 安装此包：

   npm install mcp-proxy-auth
   

2. 设置 AUTH_SERVER_URL 环境变量，使其指向您的 API 密钥验证端点：

   export AUTH_SERVER_URL=https://your-auth-server.com/verify
   

3. 运行启用身份验证的 SSE 服务：

   npx mcp-proxy-auth node dist/index.js
   

4. SSE URL 将可通过以下地址访问：

   localhost:8080/sse?apiKey=apikey
   

   将 apikey 替换为您的实际 API 密钥以进行身份验证。

mcp-proxy-auth 包充当代理，用于：

• 拦截发往 SSE 服务的请求
• 根据您的身份验证服务验证 API 密钥
• 仅允许已通过身份验证的请求访问您的 SSE 端点

与 AI 助手集成

此 MCP 服务专为支持 Model Context Protocol 的 AI 助手设计。服务运行后，会提供一组工具，兼容的 AI 助手可使用这些工具与您的 HubSpot CRM 数据交互。

可用工具

此服务提供以下强大的 HubSpot 集成工具：

1. hubspot_create_contact

   • 在 HubSpot 中创建新联系人，并检查重复项
   • 参数：
     • firstname（字符串，必填）：联系人的名字
     • lastname（字符串，必填）：联系人的姓氏
     • email（字符串，可选）：联系人的电子邮件地址
     • properties（对象，可选）：其他联系人属性，例如公司、电话等
   • 示例：

     {
       "firstname": "John",
       "lastname": "Doe",
       "email": "[email protected]",
       "properties": {
         "company": "Acme Inc",
         "phone": "555-123-4567",
         "jobtitle": "Software Engineer"
       }
     }
     

2. hubspot_create_company

   • 在 HubSpot 中创建新公司，并检查重复项
   • 参数：
     • name（字符串，必填）：公司名称
     • properties（对象，可选）：其他公司属性
   • 示例：

     {
       "name": "Acme Corporation",
       "properties": {
         "domain": "acme.com",
         "industry": "Technology",
         "phone": "555-987-6543",
         "city": "San Francisco",
         "state": "CA"
       }
     }
     

3. hubspot_get_company_activity

   • 获取特定公司的完整活动历史记录
   • 参数：
     • company_id（字符串，必填）：HubSpot 公司 ID
   • 返回详细的互动数据，包括电子邮件、电话、会议、备注和任务

4. hubspot_get_recent_engagements

   • 获取所有联系人和公司的近期互动活动
   • 参数：
     • days（数字，可选，默认值：7）：回溯天数
     • limit（数字，可选，默认值：50）：要返回的互动活动数量上限
   • 返回按时间顺序排列的所有近期 CRM 活动列表

5. hubspot_get_active_companies

   • 获取 HubSpot 中最近活跃的公司
   • 参数：
     • limit（数字，可选，默认值：10）：要返回的公司数量上限
   • 返回按最后修改日期排序的公司

6. hubspot_get_active_contacts

   • 获取 HubSpot 中最近活跃的联系人
   • 参数：
     • limit（数字，可选，默认值：10）：要返回的联系人数量上限
   • 返回按最后修改日期排序的联系人

7. hubspot_update_contact

   • 更新 HubSpot 中的现有联系人（如果联系人不存在，则忽略）
   • 参数：
     • contact_id（字符串，必填）：要更新的 HubSpot 联系人 ID
     • properties（对象，必填）：要更新的联系人属性
   • 示例：

     {
       "contact_id": "12345",
       "properties": {
         "email": "[email protected]",
         "phone": "555-987-6543",
         "jobtitle": "Senior Software Engineer"
       }
     }
     

8. hubspot_update_company

   • 更新 HubSpot 中的现有公司（如果公司不存在，则忽略）
   • 参数：
     • company_id（字符串，必填）：要更新的 HubSpot 公司 ID
     • properties（对象，必填）：要更新的公司属性
   • 示例：

     {
       "company_id": "67890",
       "properties": {
         "domain": "updated-domain.com",
         "phone": "555-123-4567",
         "industry": "Software",
         "city": "New York",
         "state": "NY"
       }
     }
     

扩展服务

此服务旨在便于扩展。要添加新的 HubSpot API 功能：

1. 在 src/hubspot-client.ts 中的 HubSpotClient 类里添加新方法
2. 在 src/index.ts 中的 setupToolHandlers 方法里注册新工具
3. 使用 npm run build 重新构建项目

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

关键词

HubSpot、CRM、Model Context Protocol、MCP、AI 助手、TypeScript、API 集成、HubSpot API、CRM 集成、联系人管理、公司管理、互动跟踪、AI 工具