AI导哈

GoHighLevel MCP客户端

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

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

使用说明

GoHighLevel MCP 客户端

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

特性/功能

  • ✅ 完整的API覆盖访问来自官方GoHighLevel MCP服务器的所有21+工具
  • 🔐 安全认证使用具有作用域权限的私有集成令牌
  • 🚀 火箭/快速上升/飞速发展（根据上下文可灵活翻译） 易于使用带有 async/await 支持的简单 JavaScript/Node.js 接口
  • 🌐 代表“地球/互联网”的符号 HTTP服务器：Web应用程序的可选REST API服务器
  • 🧪（试管/化学实验符号） 内置测试全面的测试套件以验证功能
  • 📝 TypeScript 准备就绪结构清晰、文档齐全的代码
  • ⚡（闪电符号，常用于表示快速、能量或电） 高性能支持并发请求，并具备适当的错误处理机制

快速入门

1. 安装

# Clone or download the project
cd gohighlevel-mcp-client

# Install dependencies
npm install

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工具

所需范围

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

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

错误处理

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

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文档

更新日志

v1.0.0（版本1.0.0）

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

相关 MCP