🚀 GHL MCP 服务器 - Moose v1
> 专业GoHighLevel MCP服务器,支持HTTP和STDIO
>
> 一个全面的模型上下文协议(MCP)服务器,提供对GoHighLevel API的完整访问权限,用于结合Claude Desktop和自定义AI代理实现AI自动化。
📊 项目概述
工具总数: 250个全面的GoHighLevel API集成\
服务器: 双模式(HTTP + STDIO)\
状态: 已准备好投入生产\
技术栈: TypeScript、Node.js、Express、MCP SDK、Zod
主要特点
✅ 250个工具 涵盖所有GHL运营的19个类别\
✅ 双服务器架构 - 用于Web应用的HTTP服务器,STDIO用于Claude桌面版\
✅ 类型安全 - 完整的TypeScript配合Zod模式验证\
✅ 已准备好投入生产 - 全面的错误处理和日志记录\
✅(对号,表示正确、确认或完成) 文档齐全 - 每个工具都有详细的描述\
✅ 模块化设计 - 清晰的职责分离
🎯 该服务器的功能
此MCP服务器为AI代理(如Claude桌面版或自定义ADK代理)提供直接访问您的GoHighLevel账户的途径,通过250个按以下类别组织的专用工具实现:
- 联系人管理 (32种工具) - 完整的CRM(客户关系管理)操作
- 对话与消息 (21种工具) - 短信、电子邮件、聊天
- 销售漏斗(或销售流程) (10种工具) - 机遇与交易
- 日历与约会 (14种工具) - 调度自动化
- 市场营销 (30种工具) - 电子邮件营销、社交媒体、博客
- 电子商务 (38个工具) - 仓储、产品、支付、发票
- 自定义数据 (27个工具) - 对象、字段、关联
- 自动化 (10种工具) - 工作流、调查、实用程序
> ⚠️ 此项目需要一个PRIVATE INTEGRATIONS API密钥,而不是常规的API密钥!
如何获取您的私有集成API密钥:
-
登录您的GoHighLevel账户
-
导航至设置 → 集成 → 私有集成
-
创建新的私有集成:
- 名字:
MCP Server Integration(或您喜欢的名称) - Webhook URL(中文可译为“Webhook地址”或“Webhook网址”)留空(无需填写)
- 选择所需的范围 基于你将使用的工具:
- ✅ 联系人只读权限 - 查看联系人
- ✅ 只读对话 - 查看对话
- ✅ 写入对话 - 发送消息
- ✅ 只读机会 - 查看机会
- ✅ 日历只读 - 查看日历/预约
- ✅ 日历写入 - 创建/管理预约
- ✅ 位置只读 - 查看位置数据
- ✅ 工作流只读 - 查看工作流
- ✅ 只读活动 - 查看活动
- ✅ 只读博客 - 查看博客内容
- ✅ 撰写博客 - 创建/管理博客文章
- ✅ 发票.只读 - 查看发票
- ✅ 付款.只读 - 查看支付数据
-
保存集成 并复制生成的 私人API密钥
-
复制您的位置ID 从“设置”→“公司”→“地点”
💡 小贴士: 如果您需要额外的功能,可以随时通过编辑您的私有集成来添加更多范围。
🚀 快速入门
先决条件
- Node.js 18+(推荐使用最新LTS版本)
- 带有私有集成API密钥的GoHighLevel账户
- 来自您GHL账户的有效位置ID
安装```bash
Clone the repository
git clone https://github.com/your-org/ghl-mcp-server-moose-v1.git
cd ghl-mcp-server-moose-v1
Install dependencies
npm install
Create environment file
cp .env.example .env
### 环境配置
创建一个 `.env` 根目录中的文件:```bash
# Required - GoHighLevel API Credentials
GHL_API_KEY=your_private_integrations_api_key_here
GHL_LOCATION_ID=your_location_id_here
GHL_BASE_URL=https://services.leadconnectorhq.com
# Optional - Server Configuration
PORT=9000
NODE_ENV=production
构建并运行```bash
Build the TypeScript project
npm run build
Start HTTP server (for web apps/ADK agents)
npm run start:http
Start STDIO server (for Claude Desktop)
npm run start:stdio
______________________________________________________________________
## 🌟 完整工具目录(250种工具)
### 🎯 联系人管理(32款工具)
**核心业务/核心运营:**
- `create_contact`, `search_contacts`, `get_contact`, `update_contact`, `delete_contact`
- `upsert_contact` - 智能创建/更新
- `get_duplicate_contact` - 重复检测
- `get_contacts_by_business` - 基于业务的过滤
- `get_contact_appointments` - 查看联系人的日历
**标签与组织:**
- `add_contact_tags`, `remove_contact_tags` - 个体标签管理
- `bulk_update_contact_tags` - 大规模标签操作
- `bulk_update_contact_business` - 批量业务更新
**任务管理:**
- `get_contact_tasks`, `create_contact_task`, `get_contact_task`
- `update_contact_task`, `delete_contact_task`, `update_task_completion`
**笔记管理:**
- `get_contact_notes`, `create_contact_note`, `get_contact_note`
- `update_contact_note`, `delete_contact_note`
**工作流自动化:**
- `add_contact_to_workflow`, `remove_contact_from_workflow`
- `add_contact_to_campaign`, `remove_contact_from_campaign`
- `remove_contact_from_all_campaigns`
**团队协作:**
- `add_contact_followers`, `remove_contact_followers`
### 💬 消息与对话(21款工具)
**直接沟通:**
- `send_sms`, `send_email` - 发送富格式信息
- `search_conversations`, `get_conversation`, `create_conversation`
**信息管理:**
- `get_message`, `get_email_message`, `upload_message_attachments`
- `update_message_status`, `cancel_scheduled_message`
**呼叫功能:**
- `get_message_recording`, `get_message_transcription`, `download_transcription`
- `add_inbound_message`, `add_outbound_call` - 手动记录
**在线聊天:**
- `live_chat_typing` - 实时打字状态指示器
### 📝 博客管理(7款工具)
- `create_blog_post`, `update_blog_post` - 结合SEO的内容创作
- `get_blog_posts`, `get_blog_sites` - 内容发现
- `get_blog_authors`, `get_blog_categories` - 组织
- `check_url_slug` - SEO验证
### 💰 机会管理(10种工具)
- `search_opportunities` - 按管道、阶段、联系人进行高级过滤
- `get_pipelines` - 销售漏斗管理
- `create_opportunity`, `update_opportunity`, `delete_opportunity`
- `update_opportunity_status` - 快速胜负更新
- `upsert_opportunity` - 智能管道管理
- `add_opportunity_followers`, `remove_opportunity_followers`
### 🗓️ 日历与预约(14款工具)
**日历管理:**
- `get_calendar_groups`, `get_calendars`, `create_calendar`
- `update_calendar`, `delete_calendar`
**预约安排:**
- `get_calendar_events`, `get_free_slots` - 可用性检查
- `create_appointment`, `get_appointment`, `update_appointment`, `delete_appointment`
**进度控制:**
- `create_block_slot`, `update_block_slot` - 时间区块划分
### 📧 电子邮件营销(5种工具)
- `get_email_campaigns` - 活动管理
- `create_email_template`, `get_email_templates` - 模板系统
- `update_email_template`, `delete_email_template`
### 🏢 位置管理(24种工具)
**子账户管理:**
- `search_locations`, `get_location`, `create_location`, `update_location`, `delete_location`
**标签系统:**
- `get_location_tags`, `create_location_tag`, `update_location_tag`, `delete_location_tag`
**自定义字段与值:**
- `get_location_custom_fields`, `create_location_custom_field`, `update_location_custom_field`
- `get_location_custom_values`, `create_location_custom_value`, `update_location_custom_value`
**模板与设置:**
- `get_location_templates`, `delete_location_template`, `get_timezones`
### ✅ 邮件验证(1种工具)
- `verify_email` - 可送达性及风险评估
### 📱 社交媒体管理(17种工具)
**帖子管理:**
- `search_social_posts`, `create_social_post`, `get_social_post`
- `update_social_post`, `delete_social_post`, `bulk_delete_social_posts`
**账户整合:**
- `get_social_accounts`, `delete_social_account`, `start_social_oauth`
**批量操作:**
- `upload_social_csv`, `get_csv_upload_status`, `set_csv_accounts`
**组织:**
- `get_social_categories`, `get_social_tags`, `get_social_tags_by_ids`
**平台:** 谷歌商业(Google Business)、脸书(Facebook)、照片墙(Instagram)、领英(LinkedIn)、推特(Twitter)、抖音(TikTok)
### 📁 媒体库(3种工具)
- `get_media_files` - 搜索和过滤媒体
- `upload_media_file` - 文件上传和托管URL
- `delete_media_file` - 清理媒体资产
### 🏗️ 自定义对象(9种工具)
**模式管理:**
- `get_all_objects`, `create_object_schema`, `get_object_schema`, `update_object_schema`
**记录操作:**
- `create_object_record`, `get_object_record`, `update_object_record`, `delete_object_record`
**高级搜索:**
- `search_object_records` - 查询自定义数据
**用例:** 宠物记录、支持工单、库存、自定义业务数据
### 🔗 协会管理(10种工具)
- `ghl_get_all_associations`, `ghl_create_association`, `ghl_get_association_by_id`
- `ghl_update_association`, `ghl_delete_association`
- `ghl_create_relation`, `ghl_get_relations_by_record`, `ghl_delete_relation`
- 对象间高级关系映射
### 🎛️ 自定义字段 V2(8种工具)
- `ghl_get_custom_field_by_id`, `ghl_create_custom_field`, `ghl_update_custom_field`
- `ghl_delete_custom_field`, `ghl_get_custom_fields_by_object_key`
- `ghl_create_custom_field_folder`, `ghl_update_custom_field_folder`, `ghl_delete_custom_field_folder`
### ⚡ 工作流管理(1种工具)
- `ghl_get_workflows` - 自动化工作流发现
### 📊 调查管理(2种工具)
- `ghl_get_surveys` - 调查管理
- `ghl_get_survey_submissions` - 响应分析
### 🛒 店铺管理(18款工具)
**运输区域:**
- `ghl_create_shipping_zone`, `ghl_list_shipping_zones`, `ghl_get_shipping_zone`
- `ghl_update_shipping_zone`, `ghl_delete_shipping_zone`
**运费:**
- `ghl_get_available_shipping_rates`, `ghl_create_shipping_rate`, `ghl_list_shipping_rates`
- `ghl_get_shipping_rate`, `ghl_update_shipping_rate`, `ghl_delete_shipping_rate`
**载体与环境:**
- `ghl_create_shipping_carrier`, `ghl_list_shipping_carriers`, `ghl_update_shipping_carrier`
- `ghl_create_store_setting`, `ghl_get_store_setting`
### 📦 产品管理(10种工具)
**产品运营:**
- `ghl_create_product`, `ghl_list_products`, `ghl_get_product`
- `ghl_update_product`, `ghl_delete_product`
**定价与库存:**
- `ghl_create_price`, `ghl_list_prices`, `ghl_list_inventory`
**集合:**
- `ghl_create_product_collection`, `ghl_list_product_collections`
### 💳 支付管理(20种工具)
**集成提供商:**
- `create_whitelabel_integration_provider`, `list_whitelabel_integration_providers`
**订单管理:**
- `list_orders`, `get_order_by_id`, `create_order_fulfillment`, `list_order_fulfillments`
**交易追踪:**
- `list_transactions`, `get_transaction_by_id`
**订阅管理:**
- `list_subscriptions`, `get_subscription_by_id`
**优惠券系统:**
- `list_coupons`, `create_coupon`, `update_coupon`, `delete_coupon`, `get_coupon`
**自定义支付网关:**
- `create_custom_provider_integration`, `delete_custom_provider_integration`
- `get_custom_provider_config`, `create_custom_provider_config`
### 🧾 发票与账单管理(39款工具)
**发票模板:**
- `create_invoice_template`, `list_invoice_templates`, `get_invoice_template`
- `update_invoice_template`, `delete_invoice_template`
- `update_invoice_template_late_fees`, `update_invoice_template_payment_methods`
**定期发票:**
- `create_invoice_schedule`, `list_invoice_schedules`, `get_invoice_schedule`
- `update_invoice_schedule`, `delete_invoice_schedule`, `schedule_invoice_schedule`
- `auto_payment_invoice_schedule`, `cancel_invoice_schedule`
**发票管理:**
- `create_invoice`, `list_invoices`, `get_invoice`, `update_invoice`
- `delete_invoice`, `void_invoice`, `send_invoice`, `record_invoice_payment`
- `generate_invoice_number`, `text2pay_invoice`
**估计:**
- `create_estimate`, `list_estimates`, `update_estimate`, `delete_estimate`
- `send_estimate`, `create_invoice_from_estimate`, `generate_estimate_number`
**估算模板:**
- `list_estimate_templates`, `create_estimate_template`, `update_estimate_template`
- `delete_estimate_template`, `preview_estimate_template`
**⚠️ 未实现工具说明(6个工具):**
以下工具已定义,但需要在API中实现 `ghl-api-client.ts`:
- `get_estimate` - 通过ID获取估价
- `update_estimate` - 更新现有估算
- `delete_estimate` - 删除估算
- `get_estimate_template` - 通过ID获取模板
- `update_estimate_template` - 更新模板
- `delete_estimate_template` - 删除模板
这些工具在被调用时会抛出明确的“未实现”错误。
### 🛠️ 实用工具(2件工具)
- `calculate_future_datetime` 为GHL API计算未来日期
- `calculate` - 使用函数进行安全的数学计算
______________________________________________________________________
## 🎮 使用示例
### 📞 客户沟通工作流程```
"Search for contacts tagged 'VIP' who haven't been contacted in 30 days, then send them a personalized SMS about our new premium service offering"
💰 销售漏斗管理```
"Create an opportunity for contact John Smith for our Premium Package worth $5000, add it to the 'Enterprise Sales' pipeline, and schedule a follow-up appointment for next Tuesday"
### 📊 商业智能```
"Get all invoices from the last quarter, analyze payment patterns, and create a report of our top-paying customers with their lifetime value"
🛒 电子商务运营```
"List all products with low inventory, create a restock notification campaign, and send it to contacts tagged 'inventory-manager'"
### 📱 社交媒体自动化```
"Create a social media post announcing our Black Friday sale, schedule it for all connected platforms, and track engagement metrics"
🎯 营销自动化```
"Find all contacts who opened our last email campaign but didn't purchase, add them to the 'warm-leads' workflow, and schedule a follow-up sequence"
## 🔧 开发与测试
### 可用脚本```bash
npm run build # TypeScript compilation
npm run start:http # Start HTTP server (port 9000)
npm run start:stdio # Start STDIO server for Claude Desktop
npm test # Run test suite (if configured)
测试HTTP服务器```bash
Start the HTTP server
npm run start:http
Test health endpoint
curl http://localhost:9000/health
The server will display all 250 tools on startup
### 测试STDIO服务器```bash
# The STDIO server runs silently for Claude Desktop
npm run start:stdio
# Configure in Claude Desktop (see section below)
🔌 Claude 桌面集成
配置
在您的Claude桌面MCP设置文件中添加:
地点: `~/Library/Application Support/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"ghl": {
"command": "npx",
"args": [
"/absolute/path/to/ghl-mcp-server-moose-v1/dist/stdio-server.js"
],
"env": {
"GHL_API_KEY": "your_private_integrations_api_key",
"GHL_LOCATION_ID": "your_location_id"
}
}
}
}
### 重要注意事项:
1. **使用绝对路径** - 更换 `/absolute/path/to/` 使用您实际的项目路径
1. **可执行权限** - 确保 `stdio-server.js` 具有执行权限:```bash
chmod +x dist/stdio-server.js
- 重启克劳德 - 在配置更改后,完全退出并重新启动 Claude Desktop
- 检查日志 - 如果连接失败,请检查:
~/Library/Logs/Claude/mcp*.log
🌐 部署指南
注: 随着我们向各个平台进行部署,将添加部署配置。HTTP服务器已准备好在以下平台上进行云部署:
- Vercel
- 铁路
- 渲染
- Docker 容器
- 任何Node.js托管平台
部署文档即将发布!
📋 项目架构```
ghl-mcp-server/
├── 📁 src/ # Source code
│ ├── 📁 clients/ # API client implementations
│ │ └── ghl-api-client.ts # Core GHL API client
│ ├── 📁 tools/ # MCP tool implementations
│ │ ├── contact-tools.ts # Contact management (31 tools)
│ │ ├── conversation-tools.ts # Messaging (20 tools)
│ │ ├── blog-tools.ts # Blog management (7 tools)
│ │ ├── opportunity-tools.ts # Sales pipeline (10 tools)
│ │ ├── calendar-tools.ts # Appointments (14 tools)
│ │ ├── email-tools.ts # Email marketing (5 tools)
│ │ ├── location-tools.ts # Location management (24 tools)
│ │ ├── email-isv-tools.ts # Email verification (1 tool)
│ │ ├── social-media-tools.ts # Social media (17 tools)
│ │ ├── media-tools.ts # Media library (3 tools)
│ │ ├── object-tools.ts # Custom objects (9 tools)
│ │ ├── association-tools.ts # Associations (10 tools)
│ │ ├── custom-field-v2-tools.ts # Custom fields (8 tools)
│ │ ├── workflow-tools.ts # Workflows (1 tool)
│ │ ├── survey-tools.ts # Surveys (2 tools)
│ │ ├── store-tools.ts # Store management (18 tools)
│ │ ├── products-tools.ts # Products (10 tools)
│ │ ├── payments-tools.ts # Payments (20 tools)
│ │ └── invoices-tools.ts # Invoices & billing (39 tools)
│ ├── 📁 types/ # TypeScript definitions
│ │ └── ghl-types.ts # Comprehensive type definitions
│ ├── 📁 utils/ # Utility functions
│ ├── stdio-server.ts # STDIO MCP server (Claude Desktop)
│ └── http-server.ts # HTTP MCP server (Web apps/ADK)
├── 📁 tests/ # Comprehensive test suite
│ ├── 📁 clients/ # API client tests
│ ├── 📁 tools/ # Tool implementation tests
│ └── 📁 mocks/ # Test mocks and fixtures
├── 📁 api/ # Vercel API routes
├── 📁 docker/ # Docker configurations
├── 📁 dist/ # Compiled JavaScript (auto-generated)
├── 📄 Documentation files
│ ├── DEPLOYMENT.md # Deployment guides
│ ├── CLAUDE-DESKTOP-DEPLOYMENT-PLAN.md
│ ├── VERCEL-DEPLOYMENT.md
│ ├── CLOUD-DEPLOYMENT.md
│ └── PROJECT-COMPLETION.md
├── 📄 Configuration files
│ ├── package.json # Dependencies and scripts
│ ├── tsconfig.json # TypeScript configuration
│ ├── jest.config.js # Testing configuration
│ ├── vercel.json # Vercel deployment config
│ ├── railway.json # Railway deployment config
│ ├── Dockerfile # Docker containerization
│ ├── Procfile # Process configuration
│ └── cursor-mcp-config.json # MCP configuration
└── 📄 README.md # This comprehensive guide
## 🔐 安全与最佳实践
### 环境安全
- ✅ 永远不要将API密钥提交到版本控制系统中
- ✅ 对所有敏感数据使用环境变量
- ✅ 实施适当的CORS策略
- ✅ 定期轮换API密钥
- 监控API使用情况和速率限制
### 生产考量因素
- ✅ 实现适当的错误处理和日志记录
- ✅ 设置监控和警报
- ✅ 所有部署均使用HTTPS
- ✅ 实现请求速率限制
- ✅ 定期安全更新
### API 速率限制
- GoHighLevel API 有速率限制
- 实现指数退避算法
- 缓存频繁请求的数据
- 在可用时使用批处理操作
## 🚨 故障排除指南
### 常见问题及解决方案
**构建失败:**```bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json dist/
npm install
npm run build
API连接问题:```bash
Test API connectivity (use your Private Integrations API key)
curl -H "Authorization: Bearer YOUR_PRIVATE_INTEGRATIONS_API_KEY" \
https://services.leadconnectorhq.com/locations/YOUR_LOCATION_ID
**常见API问题:**
- ✅ 使用私有集成API密钥(而非常规API密钥)
- ✅ 在私有集成中已启用所需的作用域
- ✅ 位置ID与您的GHL账户匹配
- ✅ 环境变量已正确设置
**Claude桌面集成:**
1. 验证MCP配置语法
1. 检查文件路径是否为绝对路径
1. 确保环境变量已设置
1. 更改后重启Claude桌面版
**内存问题:**```bash
# Increase Node.js memory limit
node --max-old-space-size=8192 dist/server.js
CORS 错误:
- 配置CORS_ORIGINS环境变量
- 确保使用正确的HTTP头部
- 检查域名白名单
性能优化
- 为读取操作启用响应缓存
- 对大数据集使用分页
- 实现连接池
- 监控内存使用情况并相应进行优化
📊 技术规格
系统要求
- 运行时Node.js 18+(建议使用最新长期支持版本)
- 内存最低配置512MB内存,推荐配置1GB及以上
- 存储100MB用于应用程序,额外空间用于日志
- 网络稳定的互联网连接以供API调用
技术栈
- 后端Node.js 18+ + TypeScript 5.x
- HTTP框架Express.js 5.x
- MCP SDK(MCP软件开发工具包)@modelcontextprotocol/sdk ^1.0.4
- 模式验证Zod ^3.24.1
- HTTP 客户端Axios ^1.7.9
- 构建系统TypeScript 编译器 (tsc)
API集成
- GoHighLevel API多个版本(v2021-07-28、v2021-04-15 等)
- 认证私有集成承载令牌
- 速率限制尊重GHL API的限制
- 错误处理全面的错误恢复,附带详细信息
- 模式验证所有250个工具的Zod模式
性能指标
- 冷启动小于2秒
- API 响应平均\<500毫秒
- 内存使用量~50-100MB 基础
- 工具执行平均1秒以内
📄 许可证
这个项目遵循以下许可协议: ISC许可证.
🆘 支持与资源
文档
- GoHighLevel API: 官方API文档
- MCP协议: 模型上下文协议文档
- Zod 模式(或 Zod 模式定义): Zod 文档
寻求帮助
- 查看上面的故障排除部分
- 查看Claude Desktop日志:
~/Library/Logs/Claude/mcp*.log - 验证您的私有集成API密钥和范围
- 确保所有环境变量都已正确设置
🎉 项目状态
✅ 250种操作工具 跨越19个类别
✅ 双服务器架构 (HTTP + 标准输入输出)
✅ 已准备好投入生产 具备全面的错误处理功能
✅ 类型安全 使用Zod模式进行验证
✅ 完整的TypeScript 带有完整的类型定义
✅ 表示“正确”或“勾选” 兼容Claude桌面版 使用MCP协议
✅ ADK代理准备就绪 通过HTTP服务器
✅ 文档齐全 带有丰富的工具描述
🚀 准备好自动化您的GoHighLevel工作流程了吗?
首先,按照上面的快速入门指南进行操作,配置您的私有集成API密钥,并连接您的AI代理!
由Cyberizegroup团队倾力打造💪,专为实现GoHighLevel的专业自动化而设计。
