Gohighlevel MCP

🚀 GoHighLevel MCP Server

本项目通过MCP（模型上下文协议）将GoHighLevel社区与AI自动化相连接，为用户提供了一个基础层解决方案，可访问所有子账户级别的GoHighLevel API端点，助力社区共同快速发展。

🎯 项目介绍

• 基础层：通过MCP提供对所有子账户级别的GoHighLevel API端点的访问权限。
• 社区起点：旨在推动社区更快地共同前进。
• 开放架构：API客户端和类型可根据需要进一步模块化和细分。
• 学习资源：学习如何将GoHighLevel与AI系统集成。

⚠️ 关键AI安全注意事项

• 内存/召回系统：如果未实施适当的内存或召回机制，AI可能会执行意外操作。
• 速率限制：监控API使用情况，避免达到GoHighLevel的速率限制。
• 权限控制：此项目提供对子账户API的完全访问权限，请谨慎操作。
• 数据安全：所有操作均使用您的API凭证执行，请确保采取适当的安全措施。

🎯 预期用途

• 个人/商业用途：将您自己的GoHighLevel账户与AI集成。
• 开发基础：在此基础上构建自定义解决方案。
• 学习与实验：了解GoHighLevel API模式。
• 社区贡献：帮助改进和扩展这个基础项目。

🚫 不适用场景

• 直接转售：这是免费提供的社区软件。
• 未经测试的生产环境：始终在开发环境中进行彻底测试。
• 无监控的AI使用：实施适当的保障措施和监控。

🚀 快速开始

本项目旨在通过MCP协议将GoHighLevel社区与AI自动化连接起来。在开始之前，请确保您已完成GoHighLevel API的设置，并获取所需的API密钥和位置ID。

✨ 主要特性

• 全面的工具集：提供269个操作工具，涵盖19个类别，包括联系人管理、消息传递、博客管理等。
• 实时集成：与GoHighLevel实现实时集成，覆盖完整的API。
• 多平台部署：支持在Vercel、Railway、Render、Docker等多个平台上进行生产就绪的部署。
• 企业级架构：具备全面的错误处理机制，确保系统的稳定性和可靠性。
• 完整的TypeScript支持：提供完整的类型定义，便于开发和维护。
• 广泛的测试覆盖：确保系统的可靠性和稳定性。
• Claude Desktop集成：与Claude Desktop集成，符合MCP协议。
• 社区驱动开发：拥有全面的文档，方便社区成员参与和贡献。

📦 安装指南

本地开发

前提条件

• Node.js 18+（建议使用最新的LTS版本）
• 具有API访问权限的GoHighLevel账户
• 有效的API密钥和位置ID
• Claude Desktop（用于MCP集成）

安装与设置

# 克隆仓库
git clone https://github.com/mastanley13/GoHighLevel-MCP.git
cd GoHighLevel-MCP

# 安装依赖
npm install

# 创建环境文件
cp .env.example .env
# 在.env文件中配置您的GHL凭证

# 构建项目
npm run build

# 启动服务器
npm start

# 开发环境下使用热重载
npm run dev

环境配置

# 必需的环境变量
GHL_API_KEY=your_private_integrations_api_key_here  # 来自私有集成，而非常规API密钥
GHL_BASE_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=your_location_id_here              # 来自设置 → 公司 → 位置
NODE_ENV=production

# 可选配置
PORT=8000
CORS_ORIGINS=*
LOG_LEVEL=info

可用脚本

npm run build          # TypeScript编译
npm run dev            # 开发服务器，支持热重载
npm start              # 生产环境HTTP服务器
npm run start:stdio    # 用于Claude Desktop的CLI MCP服务器
npm run start:http     # 用于Web应用的HTTP MCP服务器
npm test               # 运行测试套件
npm run test:watch     # 监视模式测试
npm run test:coverage  # 覆盖率报告
npm run lint           # TypeScript代码检查

测试与验证

# 测试API连接性
curl http://localhost:8000/health

# 列出可用工具
curl http://localhost:8000/tools

# 测试MCP SSE端点
curl -H "Accept: text/event-stream" http://localhost:8000/sse

部署指南

Vercel部署（推荐）

选项1：一键部署

选项2：手动部署

# 安装Vercel CLI
npm i -g vercel

# 部署
vercel --prod

# 在Vercel控制台中配置环境变量
# 添加：GHL_API_KEY、GHL_BASE_URL、GHL_LOCATION_ID、NODE_ENV

Vercel配置（vercel.json）：

{
  "version": 2,
  "builds": [
    {
      "src": "dist/http-server.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/dist/http-server.js"
    }
  ]
}

Railway部署

# 安装Railway CLI
npm install -g @railway/cli

# 登录并部署
railway login
railway init
railway up

# 通过Railway控制台添加环境变量

Render部署

1. 连接您的GitHub仓库。
2. 配置构建命令：npm run build。
3. 配置启动命令：npm start。
4. 在Render控制台中添加环境变量。

Docker部署

# 构建镜像
docker build -t ghl-mcp-server .

# 运行容器
docker run -p 8000:8000 \
  -e GHL_API_KEY=your_key \
  -e GHL_BASE_URL=https://services.leadconnectorhq.com \
  -e GHL_LOCATION_ID=your_location_id \
  ghl-mcp-server

💻 使用示例

📞 客户沟通工作流

"搜索标记为'VIP'且30天内未联系过的联系人，然后向他们发送一条关于我们新高级服务的个性化短信"

💰 销售管道管理

"为联系人John Smith创建一个价值5000美元的高级套餐机会，将其添加到'企业销售'管道中，并安排下周二的跟进预约"

📊 商业智能

"获取上一季度的所有发票，分析付款模式，并创建一份关于我们最高付费客户及其终身价值的报告"

🛒 电子商务运营

"列出所有库存不足的产品，创建一个补货通知活动，并将其发送给标记为'库存管理员'的联系人"

📱 社交媒体自动化

"创建一条宣布我们黑色星期五促销活动的社交媒体帖子，安排在所有连接的平台上发布，并跟踪参与度指标"

🎯 营销自动化

"查找所有打开了我们上一次电子邮件活动但未购买的联系人，将他们添加到'潜在客户'工作流中，并安排后续跟进序列"

📚 详细文档

项目架构

ghl-mcp-server/
├── 📁 src/                    # 源代码
│   ├── 📁 clients/            # API客户端实现
│   │   └── ghl-api-client.ts  # 核心GHL API客户端
│   ├── 📁 tools/              # MCP工具实现
│   │   ├── contact-tools.ts   # 联系人管理（31个工具）
│   │   ├── conversation-tools.ts # 消息传递（20个工具）
│   │   ├── blog-tools.ts      # 博客管理（7个工具）
│   │   ├── opportunity-tools.ts # 销售管道（10个工具）
│   │   ├── calendar-tools.ts  # 预约管理（14个工具）
│   │   ├── email-tools.ts     # 电子邮件营销（5个工具）
│   │   ├── location-tools.ts  # 位置管理（24个工具）
│   │   ├── email-isv-tools.ts # 电子邮件验证（1个工具）
│   │   ├── social-media-tools.ts # 社交媒体（17个工具）
│   │   ├── media-tools.ts     # 媒体库（3个工具）
│   │   ├── object-tools.ts    # 自定义对象（9个工具）
│   │   ├── association-tools.ts # 关联管理（10个工具）
│   │   ├── custom-field-v2-tools.ts # 自定义字段（8个工具）
│   │   ├── workflow-tools.ts  # 工作流管理（1个工具）
│   │   ├── survey-tools.ts    # 调查管理（2个工具）
│   │   ├── store-tools.ts     # 商店管理（18个工具）
│   │   ├── products-tools.ts  # 产品管理（10个工具）
│   │   ├── payments-tools.ts  # 支付管理（20个工具）
│   │   └── invoices-tools.ts  # 发票与账单管理（39个工具）
│   ├── 📁 types/              # TypeScript类型定义
│   │   └── ghl-types.ts       # 全面的类型定义
│   ├── 📁 utils/              # 实用函数
│   ├── server.ts              # CLI MCP服务器（Claude Desktop）
│   └── http-server.ts         # HTTP MCP服务器（Web应用）
├── 📁 tests/                  # 全面的测试套件
│   ├── 📁 clients/            # API客户端测试
│   ├── 📁 tools/              # 工具实现测试
│   └── 📁 mocks/              # 测试模拟和夹具
├── 📁 api/                    # Vercel API路由
├── 📁 docker/                 # Docker配置
├── 📁 dist/                   # 编译后的JavaScript（自动生成）
├── 📄 文档文件
│   ├── DEPLOYMENT.md          # 部署指南
│   ├── CLAUDE-DESKTOP-DEPLOYMENT-PLAN.md
│   ├── VERCEL-DEPLOYMENT.md
│   ├── CLOUD-DEPLOYMENT.md
│   └── PROJECT-COMPLETION.md
├── 📄 配置文件
│   ├── package.json           # 依赖项和脚本
│   ├── tsconfig.json          # TypeScript配置
│   ├── jest.config.js         # 测试配置
│   ├── vercel.json            # Vercel部署配置
│   ├── railway.json           # Railway部署配置
│   ├── Dockerfile             # Docker容器化配置
│   ├── Procfile               # 进程配置
│   └── cursor-mcp-config.json # MCP配置
└── 📄 README.md               # 本综合指南

安全与最佳实践

环境安全

• ✅ 切勿将API密钥提交到版本控制中。
• ✅ 使用环境变量存储所有敏感数据。
• ✅ 实施适当的CORS策略。
• ✅ 定期轮换API密钥。
• ✅ 监控API使用情况和速率限制。

生产环境考虑

• ✅ 实施适当的错误处理和日志记录。
• ✅ 设置监控和警报。
• ✅ 所有部署均使用HTTPS。
• ✅ 实施请求速率限制。
• ✅ 定期进行安全更新。

API速率限制

• GoHighLevel API有速率限制。
• 实施指数退避策略。
• 缓存频繁请求的数据。
• 尽可能使用批量操作。

故障排除指南

常见问题与解决方案

构建失败：

# 清除缓存并重新安装
rm -rf node_modules package-lock.json dist/
npm install
npm run build

API连接问题：

# 测试API连接性（使用您的私有集成API密钥）
curl -H "Authorization: Bearer YOUR_PRIVATE_INTEGRATIONS_API_KEY" \
     https://services.leadconnectorhq.com/locations/YOUR_LOCATION_ID

常见API问题：

• ✅ 使用私有集成API密钥（而非常规API密钥）。
• ✅ 在私有集成中启用所需的作用域。
• ✅ 位置ID与您的GHL账户匹配。
• ✅ 正确设置环境变量。

Claude Desktop集成问题：

1. 验证MCP配置语法。
2. 检查文件路径是否为绝对路径。
3. 确保环境变量已设置。
4. 更改后重新启动Claude Desktop。

内存问题：

# 增加Node.js内存限制
node --max-old-space-size=8192 dist/server.js

CORS错误：

• 配置CORS_ORIGINS环境变量。
• 确保HTTP头正确。
• 检查域名白名单。

性能优化

• 为读取操作启用响应缓存。
• 对大数据集使用分页。
• 实施连接池。
• 监控内存使用情况并相应地进行优化。

🔧 技术细节

系统要求

• 运行时：Node.js 18+（建议使用最新的LTS版本）
• 内存：最小512MB RAM，推荐1GB以上
• 存储：应用程序需要100MB，日志需要额外空间
• 网络：稳定的互联网连接，用于API调用

技术栈

• 后端：Node.js + TypeScript
• HTTP框架：Express.js 5.x
• MCP SDK：@modelcontextprotocol/sdk ^1.12.1
• HTTP客户端：Axios ^1.9.0
• 测试：Jest，支持TypeScript
• 构建系统：TypeScript编译器

API集成

• GoHighLevel API：v2021-07-28（联系人），v2021-04-15（对话）
• 身份验证：Bearer令牌
• 速率限制：遵守GHL API限制
• 错误处理：全面的错误恢复机制

性能指标

• 冷启动：< 2秒
• API响应：平均< 500ms
• 内存使用：基础约50 - 100MB
• 工具执行：平均< 1秒

📄 许可证

本项目采用ISC许可证，详情请参阅LICENSE文件。

🆘 社区与支持

文档

• 📖 完整API文档
• 🎥 视频教程
• 📋 工具参考指南
• 🔧 部署指南

获取帮助

• 问题反馈：GitHub Issues
• 讨论交流：GitHub Discussions
• API参考：GoHighLevel API文档
• MCP协议：模型上下文协议

社区资源

• 💬 加入我们的Discord社区
• 📺 订阅我们的YouTube频道
• 📰 关注我们的开发博客
• 🐦 关注我们的Twitter获取更新

🎉 成功指标

• ✅ 269个操作工具，涵盖19个类别
• ✅ 实时GoHighLevel集成，全面覆盖API
• ✅ 多平台生产就绪部署
• ✅ 企业级架构，具备全面的错误处理机制
• ✅ 完整的TypeScript支持，提供完整的类型定义
• ✅ 广泛的测试覆盖，确保可靠性
• ✅ 多平台部署（Vercel、Railway、Render、Docker）
• ✅ Claude Desktop集成，符合MCP协议
• ✅ 社区驱动开发，拥有全面的文档

🚀 准备好彻底改变您的GoHighLevel自动化了吗？

立即部署，释放AI驱动的CRM管理的全部潜力！

💝 支持本项目

本项目凝聚了数百小时的开发工作，旨在帮助GoHighLevel社区。如果它为您节省了时间并对您的业务有所帮助，请考虑支持其持续发展：

🎁 支持方式

• ⭐ 给这个仓库加星：帮助他人发现该项目。
• 🍕 请我吃披萨：通过Stripe捐赠
• 🐛 报告漏洞：帮助大家让项目变得更好。
• 💡 提出功能建议：分享您的改进想法。
• 🤝 贡献代码：随时欢迎提交拉取请求！

🏆 认可方式

• 贡献者将在项目中列出。
• 重大贡献可能会获得特别认可。
• 本项目由社区驱动并得到社区支持。

每一份贡献，无论大小，都有助于让这个项目持续发展！ 🚀

由了解自动化力量的开发者为GoHighLevel社区精心打造 ❤️