AI导哈

GoHighLevel MCP客户端

一个强大的Node.js客户端，用于与GoHighLevel MCP服务器交互，提供管理联系人、对话、日历、机会和支付的功能。

  • by CryptoJym
  • JavaScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 CryptoJym/gohighlevel-mcp

使用说明

GoHighLevel MCP 客户端

一个强大的Node.js客户端，用于与官方GoHighLevel MCP（模型上下文协议）服务器进行交互。此客户端提供了一个简洁的界面，用于管理您GoHighLevel账户中的联系人、对话、日历、商机和支付信息。

特点/功能

  • ✅ 完整的API覆盖访问官方GoHighLevel MCP服务器上的所有21+工具
  • 🔐 安全认证使用具有范围权限的私有集成令牌
  • 🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或“发射”，用于表示快速前进、加速或高科技等概念。在没有具体上下文的情况下，这个符号本身就可以直接理解为“火箭”或“发射”的意思。 易于使用支持异步/等待的简单JavaScript/Node.js接口
  • 🌐 表示“互联网”或“全球网络”。 HTTP服务器用于Web应用程序的可选REST API服务器
  • 🧪 试管/实验器材（通常用于表示进行科学实验或化学反应的场景） 内置测试全面的测试套件以验证功能
  • 📝（便签本/笔记） TypeScript 准备就绪代码结构清晰，文档齐全
  • ⚡（闪电符号，常用于表示快速、能量或电子设备等概念，在此无具体上下文，故仅作符号翻译） 高性能支持并发请求并具备适当的错误处理

快速入门

1. 安装

# Clone from GitHub
git clone https://github.com/CryptoJym/gohighlevel-mcp.git
cd gohighlevel-mcp

# Install dependencies
npm install

# Run interactive setup
npm run setup

设置向导将引导您完成配置并测试您的连接。

有关详细的团队入职指南，请参阅 INSTALL.md 翻译为中文是：“安装说明文件”

2. 手动配置（备选方案）

如果您更喜欢手动设置：

cp .env.example .env

编辑 .env 附上您的GoHighLevel凭据文件：

GHL_PRIVATE_INTEGRATION_TOKEN=pit-your-token-here
GHL_LOCATION_ID=your-location-id-here

3. 获取您的凭证

私人集成代币：

  1. 登录您的GoHighLevel账户
  2. 首选 设置 > 私有集成
  3. 点击 “创建新集成”
  4. 选择所需的范围（见 所需范围）
  5. 复制生成的令牌

位置ID：

  • 这是您在GoHighLevel中的子账户ID
  • 在查看您的位置时，可以在URL中找到它
  • 或者使用客户端来检索它： node index.js location

4. 测试连接

npm test
# or
node test.js

使用方法

命令行界面

# Test connection
node index.js test

# Get all contacts
node index.js contacts

# Get specific contact
node index.js contact <contact-id>

# Get location info
node index.js location

# List available tools
node index.js tools

# Start HTTP server
node index.js server

程序化使用

import GoHighLevelMCPClient from './index.js';

const client = new GoHighLevelMCPClient();

// Get contacts
const contacts = await client.getContacts({ limit: 10 });
console.log(contacts);

// Create a new contact
const newContact = await client.createContact({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  phone: '+1234567890'
});

// Send a message
const message = await client.sendMessage(conversationId, 'Hello!');

HTTP服务器API

启动服务器：

node index.js server

可用的终端节点：

  • GET /health - 健康检查
  • GET /test - 测试连接
  • GET /tools - 列出可用工具
  • GET /contacts - 获取联系人
  • GET /contacts/:id - 获取特定联系人
  • POST /contacts - 创建联系人
  • PUT /contacts/:id - 更新联系人
  • GET /conversations - 搜索对话
  • GET /conversations/:id/messages - 获取消息
  • POST /conversations/:id/messages - 发送消息
  • GET /location - 获取位置信息
  • GET /location/custom-fields - 获取自定义字段

可用方法

联系人管理

  • getContacts(params) - 获取所有联系人，并可选择性过滤
  • getContact(contactId) - 通过ID获取特定联系人
  • createContact(contactData) - 创建新联系人
  • updateContact(contactId, contactData) - 更新现有联系人
  • upsertContact(contactData) - 创建或更新联系人
  • addTagsToContact(contactId, tags) - 为联系人添加标签
  • removeTagsFromContact(contactId, tags) - 从联系人中移除标签
  • getAllTasks(contactId) - 获取联系人的所有任务

对话管理

  • searchConversations(params) - 搜索并筛选对话
  • getMessages(conversationId) - 获取对话中的消息
  • sendMessage(conversationId, message) - 发送新消息

日历管理

  • getCalendarEvents(params) - 获取日历事件
  • getAppointmentNotes(appointmentId) - 获取预约记录

机会管理

  • searchOpportunities(params) - 寻找机会
  • getOpportunity(opportunityId) - 获取特定机会
  • updateOpportunity(opportunityId, data) - 更新机会
  • getPipelines() - 获取所有销售机会管道

支付管理

  • getOrderById(orderId) - 获取订单详情
  • listTransactions(params) - 列出并过滤交易

位置管理

  • getLocation(locationId) - 获取位置/子账户详细信息
  • getCustomFields(locationId) - 获取自定义字段定义

实用方法

  • testConnection() - 测试与GoHighLevel的连接
  • getAvailableTools() - 列出所有可用的MCP工具

🔧 与AI工具的集成

克劳德桌面（或“克劳德电脑版”，具体翻译可能根据上下文调整）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)：

{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gohighlevel-mcp/gohighlevel-mcp-proxy.mjs"],
      "env": {
        "GHL_PRIVATE_INTEGRATION_TOKEN": "pit-YOUR-TOKEN",
        "GHL_LOCATION_ID": "YOUR-LOCATION-ID",
        "DEBUG": "false"
      }
    }
  }
}

重启Claude桌面应用后，您将看到21个GoHighLevel工具可供使用。

VS Code / Cursor / Codex

看 INSTALL.md 翻译为中文是：“安装指南文件（或：安装说明文档）” 以下是详细的配置示例：

  • 带有Claude Dev/Roo Cline的VS Code
  • 光标
  • 《Codex》（拉丁语，意为“法典”或“典籍”）
  • 其他兼容MCP的工具

所需范围

在创建您的私有集成令牌时，请确保选择以下范围：

  • ✅ 查看联系人
  • ✅ 编辑联系人
  • ✅ 查看对话
  • ✅ 编辑对话
  • ✅ 查看对话消息
  • ✅ 编辑对话消息
  • ✅ 查看机会
  • ✅ 编辑机会
  • ✅ 查看日历
  • ✅ 编辑日历事件
  • ✅ 编辑日历
  • ✅ 查看付款订单
  • ✅ 查看支付交易
  • ✅ 查看自定义字段
  • ✅ 查看表单
  • ✅ 查看位置

错误处理

客户端包含全面的错误处理机制：

const result = await client.getContacts();

if (result.success) {
  console.log('Data:', result.data);
} else {
  console.log('Error:', result.error);
  console.log('Status:', result.status);
}

测试

运行测试套件以验证您的设置：

# Basic functionality tests
npm test

# Performance tests
node test.js performance

# All tests
node test.js all

环境变量

变量 必填 描述
GHL_PRIVATE_INTEGRATION_TOKEN 是 您的GoHighLevel私有集成令牌
GHL_LOCATION_ID 推荐 您的GoHighLevel位置/子账户ID
GHL_MCP_URL 编号 MCP 服务器 URL（默认为官方服务器）
PORT 编号 HTTP 服务器端口（默认：3000）
HOST 编号 HTTP 服务器主机（默认：localhost）
DEBUG 编号 启用调试日志记录（默认：false）

故障排除

常见问题

  1. "GHL_PRIVATE_INTEGRATION_TOKEN 是必需的"

    • 确保你的 .env 文件存在且包含令牌
    • 验证令牌格式是否正确（以 pit-)

  2. “需要位置ID”

    • 某些操作需要位置ID
    • 设定 GHL_LOCATION_ID 在你的 .env 文件
    • 或者将其作为参数传递给特定方法

  3. 认证错误

    • 验证您的令牌是否具有所需的范围
    • 检查令牌是否已过期
    • 确保您使用的是正确的地点ID

  4. 连接超时

    • 检查您的网络连接
    • 验证MCP服务器URL是否正确
    • 尝试在客户端配置中增加超时时间

调试模式

启用调试日志以查看详细的请求信息：

DEBUG=true node index.js test

做出贡献

  1. 为仓库创建分支
  2. 创建一个特性分支
  3. 做出你的更改
  4. 为新功能添加测试
  5. 运行测试套件
  6. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

对于以下相关问题：

  • 这个客户在这个仓库中打开一个问题（或议题）
  • GoHighLevel API联系GoHighLevel支持团队
  • MCP协议查阅官方的MCP文档

更改日志

版本1.0.0

  • 初始发布
  • 完整的MCP客户端实现
  • HTTP服务器接口
  • 全面的测试套件
  • 完整文档

相关 MCP