Ghl Mcp Server

数据库 JavaScript

🚀 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 许可证。

📚 支持

0 条评论
分类：数据库