金大哥 - ghl-mcp-server MCP 详情

article

README

🚀 GoHighLevel MCP 服务器

这是一个模型上下文协议（MCP）服务器，可与 GoHighLevel API v2 进行全面集成。该服务器使 AI 助手能够与 GoHighLevel 的客户关系管理（CRM）、营销自动化和业务管理工具进行交互。

✨ 主要特性

🚀 完整的 API 覆盖：可访问联系人、对话、日历、销售机会、支付、工作流等功能。
🔐 灵活的身份验证：支持 OAuth 2.0 和私有集成令牌两种方式。
⚡ 内置速率限制：自动进行速率限制管理（每 10 秒 100 个请求，每天 200,000 个请求）。
🛡️ 错误处理：具备全面的错误处理机制，提供详细的错误信息。
📦 支持 Vercel 部署：专为在 Vercel 上部署而设计，支持 MCP。
🎯 类型安全：对所有工具进行全面的输入验证和模式定义。

📦 安装指南

可以使用以下命令进行安装：

npm install ghl-mcp-server

或者进行全局安装：

npm install -g ghl-mcp-server

🚀 快速开始

1. 设置环境变量

将 .env.example 文件复制为 .env，并填写你的凭证信息：

cp .env.example .env

编辑 .env 文件，填入你的 GoHighLevel 凭证：

# 私有集成令牌（最简单的方法）
GHL_PRIVATE_TOKEN=your_private_integration_token_here

# 或者使用 OAuth（用于多账户访问）
GHL_CLIENT_ID=your_oauth_client_id
GHL_CLIENT_SECRET=your_oauth_client_secret

2. 配置你的 MCP 客户端

将以下内容添加到你的 Claude Desktop 或其他 MCP 客户端配置中：

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["ghl-mcp-server"],
      "env": {
        "GHL_PRIVATE_TOKEN": "your_token_here"
      }
    }
  }
}

3. 开始使用 GoHighLevel 工具

该服务器提供以下工具：

联系人管理

ghl_create_contact - 创建新联系人
ghl_search_contacts - 搜索联系人
ghl_get_contact - 获取联系人详情
ghl_update_contact - 更新联系人信息
ghl_delete_contact - 删除联系人
ghl_add_contact_tags - 为联系人添加标签
ghl_remove_contact_tags - 移除联系人的标签

对话与消息

ghl_send_message - 发送短信、电子邮件或 WhatsApp 消息
ghl_get_conversations - 获取对话列表
ghl_get_messages - 获取对话中的消息

日历与预约

ghl_create_calendar - 创建新日历
ghl_create_appointment - 预订预约
ghl_get_calendar_slots - 获取可用时间段
ghl_update_appointment - 更新预约详情
ghl_cancel_appointment - 取消预约

销售与机会

ghl_create_opportunity - 创建销售机会
ghl_search_opportunities - 搜索销售机会
ghl_update_opportunity - 更新销售机会详情
ghl_delete_opportunity - 删除销售机会
ghl_get_pipelines - 获取销售管道列表

支付

ghl_create_order - 创建支付订单
ghl_get_transactions - 获取交易历史
ghl_get_orders - 获取订单列表

自动化

ghl_add_contact_to_workflow - 将联系人添加到工作流
ghl_remove_contact_from_workflow - 从工作流中移除联系人
ghl_get_workflows - 获取工作流列表

💻 使用示例

基础用法

创建联系人

{
  "tool": "ghl_create_contact",
  "arguments": {
    "locationId": "your_location_id",
    "contactData": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "tags": ["new-lead", "website"]
    }
  }
}

发送消息

{
  "tool": "ghl_send_message",
  "arguments": {
    "type": "SMS",
    "contactId": "contact_id",
    "locationId": "location_id",
    "message": "Hello! Thanks for your interest."
  }
}

创建预约

{
  "tool": "ghl_create_appointment",
  "arguments": {
    "appointmentData": {
      "calendarId": "calendar_id",
      "locationId": "location_id",
      "contactId": "contact_id",
      "startTime": "2025-07-23T15:00:00Z",
      "endTime": "2025-07-23T16:00:00Z",
      "title": "Consultation Call"
    }
  }
}

🔐 身份验证方法

方法 1：私有集成令牌（适用于单账户，推荐使用）

进入 GoHighLevel 的“设置”>“集成”>“私有集成”。
创建一个新的私有集成。
复制令牌并添加到你的 .env 文件中。

方法 2：OAuth 2.0（适用于市场应用）

在 GoHighLevel 市场中注册你的应用。
使用所需的范围设置 OAuth。
通过 OAuth 流程获取访问令牌。

🔧 技术细节

本地运行

# 安装依赖
npm install

# 在开发模式下运行
npm run dev

项目结构

ghl-mcp-server/
├── index.js              # 主服务器入口点
├── src/
│   ├── api-client.js     # GoHighLevel API 客户端
│   ├── config.js         # 配置常量
│   ├── rate-limiter.js   # 速率限制逻辑
│   ├── error-handler.js  # 错误处理工具
│   └── tools/            # 工具定义
│       ├── contact-tools.js
│       ├── conversation-tools.js
│       ├── calendar-tools.js
│       ├── opportunity-tools.js
│       ├── payment-tools.js
│       └── workflow-tools.js
└── package.json

🚀 部署到 Vercel

分叉此仓库。
连接到 Vercel。
在 Vercel 控制台中设置环境变量。
进行部署。

该服务器设计为可直接与 Vercel 的 MCP 集成配合使用。

🛡️ 错误处理

服务器针对常见场景提供详细的错误信息：

401 未授权：令牌无效或已过期。
403 禁止访问：权限/范围不足。
404 未找到：资源未找到。
429 速率限制：请求过多。
422 不可处理的实体：验证错误。

⚡ 速率限制

GoHighLevel 实施以下速率限制：

突发：每 10 秒 100 个请求。
每日：每天 200,000 个请求。

服务器会自动跟踪并执行这些限制。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

📄 许可证

本项目采用 MIT 许可证。

ghl-mcp-server