AI导哈

HubSpot CRM集成服务器

一个与HubSpot CRM无缝集成的模型上下文协议（MCP）服务器，使AI助手能够高效管理联系人、公司、交易等数据。

  • by Manhar-Chaurasia
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Manhar-Chaurasia/mcp

使用说明

HubSpot MCP服务器

一个模型上下文协议（MCP）服务器，可与HubSpot CRM无缝集成。该服务器使Claude等人工智能助手能够与您的HubSpot数据交互，从而高效管理联系人、公司、交易等。

🚀 特性

  • 联系人管理：在HubSpot中创建、阅读、更新和搜索联系人
  • 公司管理：管理公司记录和信息
  • 交易管理：跟踪和更新销售机会
  • 电子邮件集成：发送电子邮件并跟踪参与情况（需要设置）
  • 类型安全：使用TypeScript构建，以获得更好的开发体验
  • 综合测试：包括单元测试和集成示例
  • 轻松设置：使用环境变量进行简单配置

📋 可用工具

联系人

  • get_contacts -检索联系人列表
  • get_contact -通过ID获取特定联系人
  • create_contact -创建新联系人
  • update_contact -更新现有联系人
  • search_contacts -搜索联系人

公司

  • get_companies -检索公司列表
  • get_company -通过ID获取特定公司
  • create_company -创建新公司
  • update_company -更新现有公司

交易

  • get_deals -检索交易列表
  • get_deal -按ID获取特定交易
  • create_deal -创建新交易
  • update_deal -更新现有交易

电子邮件

  • send_email -通过HubSpot发送电子邮件（需要营销电子邮件API）
  • get_email_events -获取电子邮件参与数据（需要事件API）

🛠️ 先决条件

  • Node.js 18+和npm
  • 具有API访问权限的HubSpot帐户
  • HubSpot API密钥或OAuth凭据

📦 安装

  1. 克隆存储库:

    git clone https://github.com/yourusername/hubspot-mcp-server.git
cd hubspot-mcp-server

  2. 安装依赖项:

    npm install

  3. 配置环境变量:

    cp .env.example .env

    编辑 .env 使用您的HubSpot凭据：

    HUBSPOT_API_KEY=your_hubspot_api_key_here
# OR use OAuth (if you prefer)
HUBSPOT_CLIENT_ID=your_client_id
HUBSPOT_CLIENT_SECRET=your_client_secret
HUBSPOT_ACCESS_TOKEN=your_access_token

  4. 构建项目:

    npm run build

🔧 获取HubSpot API凭据

选项1：API密钥（建议用于测试）

  1. 转到HubSpot设置→ 集成→ API密钥
  2. 生成新的API密钥
  3. 将其添加到您的 .env 文件为 HUBSPOT_API_KEY

选项2:OAuth应用程序（建议用于生产环境）

  1. 转到HubSpot开发人员帐户→ Apps
  2. 创建新应用程序
  3. 记下您的客户端ID和客户端密码
  4. 配置OAuth重定向类型
  5. 将凭据添加到您的 .env 文件

🚀 用法

使用克劳德桌面

  1. 配置Claude桌面 通过添加到MCP设置中：

    {
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/hubspot-mcp-server",
      "env": {
        "HUBSPOT_API_KEY": "your_api_key_here"
      }
    }
  }
}

  2. 重新启动克劳德桌面

  3. 开始使用HubSpot工具 克劳德：

    • “显示我最近的联系人”
    • “通过电子邮件为John Doe创建新联系人john@example.com"
    • “搜索技术行业的公司”

直接使用

您也可以直接运行服务器：

npm start

或者用于自动重新加载的开发：

npm run dev

🧪 测试

运行测试套件：

npm test

在监视模式下运行测试：

npm run test:watch

运行服务器的手动测试：

npm run dev
# In another terminal:
node tests/test-server.js

📖 示例

创建联系人

// Using the MCP tool
{
  "tool": "create_contact",
  "arguments": {
    "email": "jane.doe@example.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "+1-555-123-4567",
    "company": "Example Corp",
    "lifecyclestage": "lead"
  }
}

搜索公司

// This would be handled automatically by Claude when you ask:
// "Find all companies in the software industry"
{
  "tool": "get_companies",
  "arguments": {
    "limit": 20,
    "properties": ["name", "domain", "industry", "city", "state"]
  }
}

🏗️ 发展

项目结构

src/
├── index.ts              # Main MCP server
├── services/
│   └── hubspot.ts        # HubSpot API wrapper
├── tools/
│   ├── base.ts           # Base tool class
│   ├── contacts.ts       # Contact management tools
│   ├── companies.ts      # Company management tools
│   ├── deals.ts          # Deal management tools
│   └── emails.ts         # Email tools
└── types/
    └── index.ts          # Type definitions

tests/
├── setup.ts              # Test configuration
├── hubspot.service.test.ts
├── contacts.tool.test.ts
└── test-server.ts        # Manual testing script

添加新工具

  1. 创建一个新的工具类来扩展 BaseTool
  2. 实施 getTools() 和 executeTool() 方法
  3. 在中注册该工具 src/index.ts
  4. 为新工具添加测试

代码的风格

此项目使用启用严格模式的TypeScript。确保：

  • 使用正确的类型注释
  • 遵循现有的命名约定
  • 为公共方法添加JSDoc注释
  • 为新功能编写测试

🔒 安全考虑

  • API密钥：从不将API密钥提交到版本控制
  • 环境变量：使用 .env 本地开发文件
  • 生产：在生产中使用适当的秘密管理
  • 速率限制：注意HubSpot API费率限制
  • 权限：仅请求必要的HubSpot示波器

📚 资源

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature/amazing-feature
  3. 提交您的更改： git commit -m 'Add amazing feature'
  4. 推到分支： git push origin feature/amazing-feature
  5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🐛 故障排除

常见问题

“找不到API密钥”错误:

  • 确保您的 .env 文件配置正确
  • 检查API密钥是否有效并具有必要的权限

“找不到模块”错误:

  • 跑 npm install 确保所有依赖项都已安装
  • 跑 npm run build 编译TypeScript

速率限制错误:

  • HubSpot有API费率限制。为生产使用实施适当的重试逻辑
  • 考虑对失败的请求使用指数回退

连接超时:

  • 检查您的互联网连接
  • 验证HubSpot服务状态

如需更多帮助，请 打开一个问题.

🚀 部署

生产注意事项

  1. 环境变量：使用适当的秘密管理系统
  2. 日志记录：配置适当的日志级别
  3. 监控：建立健康检查和监测
  4. 扩展：考虑对高容量使用进行速率限制和缓存

Docker支持（即将推出）

Docker支持将在未来的版本中添加，以便于部署。

内置于❤️ HubSpot和人工智能社区

相关 MCP