🚀 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种工具) - 工作流、调查、实用程序
______________________________________________________________________
🔑 翻译成中文是“钥匙”。 CRITICAL:GoHighLevel API 设置
根据上述信息,以下是原文内容的翻译:📋 必填:私有集成API密钥
⚠️ 此项目需要一个PRIVATE INTEGRATIONS API密钥,而不是常规的API密钥!
如何获取您的私有集成API密钥:
- 登录您的GoHighLevel账户
- 导航至设置 → 集成 → 私有集成
- 创建新的私有集成:
- 名字: MCP Server Integration (或您喜欢的名称) - Webhook URL(中文可译为“Webhook地址”或“Webhook网址”)留空(无需填写)
- 选择所需的范围 基于你将使用的工具:
- ✅ 联系人只读权限 - 查看联系人 - ✅ contacts.write 翻译成中文是“写入联系人” - 创建/更新联系人 - ✅ 只读对话 - 查看对话 - ✅ 写入对话 - 发送消息 - ✅ 只读机会 - 查看机会 - ✅(这个符号在中文里通常被用作“正确”或“确认”的标志,没有直接的中文翻译,但可以根据上下文理解为“正确”、“确认”或“完成”等意思。) 机遇撰写(或“机遇记录”) - 管理机会 - ✅ 日历只读 - 查看日历/预约 - ✅ 日历写入 - 创建/管理预约 - ✅ 位置只读 - 查看位置数据 - ✅ locations.write(可翻译为“位置写入”或根据上下文具体解释为相应的操作,如“将位置信息写入”) - 管理位置设置 - ✅ 工作流只读 - 查看工作流 - ✅ 只读活动 - 查看活动 - ✅ 只读博客 - 查看博客内容 - ✅ 撰写博客 - 创建/管理博客文章 - ✅ users.readonly(可翻译为)“用户只读” - 查看用户信息 - ✅(对号,表示正确、同意或确认) custom_objects.readonly 翻译为中文是:“自定义对象只读” - 查看自定义对象 - ✅ custom_objects.write 翻译成中文是:“自定义对象写入” - 管理自定义对象 - ✅ 发票.只读 - 查看发票 - ✅ 发票.write(注:这里的“write”可能是一个动作或功能的指示,在中文中可能需要根据上下文具体翻译,比如“开具发票”或“编写发票信息”,但直接翻译“invoices.write”为“发票.write”保持了原样的形式,实际使用时可能需要根据语境调整。) - 创建/管理发票 - ✅ 付款.只读 - 查看支付数据 - ✅ products.readonly 翻译为中文是:“产品只读” - 查看产品 - ✅ products.write 翻译为中文是“产品撰写”或“产品编写” - 管理产品
- 保存集成 并复制生成的 私人API密钥
- 复制您的位置ID 从“设置”→“公司”→“地点”
💡 小贴士: 如果您需要额外的功能,可以随时通过编辑您的私有集成来添加更多范围。
______________________________________________________________________
🚀 快速入门
先决条件
- Node.js 18+(推荐使用最新LTS版本)
- 带有私有集成API密钥的GoHighLevel账户
- 来自您GHL账户的有效位置ID
安装
# 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 根目录中的文件:
# 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构建并运行
# 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_contactupsert_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_taskupdate_contact_task,delete_contact_task,update_task_completion
笔记管理:
get_contact_notes,create_contact_note,get_contact_noteupdate_contact_note,delete_contact_note
工作流自动化:
add_contact_to_workflow,remove_contact_from_workflowadd_contact_to_campaign,remove_contact_from_campaignremove_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_attachmentsupdate_message_status,cancel_scheduled_message
呼叫功能:
get_message_recording,get_message_transcription,download_transcriptionadd_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_opportunityupdate_opportunity_status- 快速胜负更新upsert_opportunity- 智能管道管理add_opportunity_followers,remove_opportunity_followers
🗓️ 日历与预约(14款工具)
日历管理:
get_calendar_groups,get_calendars,create_calendarupdate_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_fieldget_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_postupdate_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- 文件上传和托管URLdelete_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_idghl_update_association,ghl_delete_associationghl_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_fieldghl_delete_custom_field,ghl_get_custom_fields_by_object_keyghl_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_zoneghl_update_shipping_zone,ghl_delete_shipping_zone
运费:
ghl_get_available_shipping_rates,ghl_create_shipping_rate,ghl_list_shipping_ratesghl_get_shipping_rate,ghl_update_shipping_rate,ghl_delete_shipping_rate
载体与环境:
ghl_create_shipping_carrier,ghl_list_shipping_carriers,ghl_update_shipping_carrierghl_create_store_setting,ghl_get_store_setting
📦 产品管理(10种工具)
产品运营:
ghl_create_product,ghl_list_products,ghl_get_productghl_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_integrationget_custom_provider_config,create_custom_provider_config
🧾 发票与账单管理(39款工具)
发票模板:
create_invoice_template,list_invoice_templates,get_invoice_templateupdate_invoice_template,delete_invoice_templateupdate_invoice_template_late_fees,update_invoice_template_payment_methods
定期发票:
create_invoice_schedule,list_invoice_schedules,get_invoice_scheduleupdate_invoice_schedule,delete_invoice_schedule,schedule_invoice_scheduleauto_payment_invoice_schedule,cancel_invoice_schedule
发票管理:
create_invoice,list_invoices,get_invoice,update_invoicedelete_invoice,void_invoice,send_invoice,record_invoice_paymentgenerate_invoice_number,text2pay_invoice
估计:
create_estimate,list_estimates,update_estimate,delete_estimatesend_estimate,create_invoice_from_estimate,generate_estimate_number
估算模板:
list_estimate_templates,create_estimate_template,update_estimate_templatedelete_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"🔧 开发与测试
可用脚本
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服务器
# 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服务器
# 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
{
"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"
}
}
}
}重要注意事项:
- 使用绝对路径 - 更换
/absolute/path/to/使用您实际的项目路径 - 可执行权限 - 确保
stdio-server.js具有执行权限:
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 有速率限制
- 实现指数退避算法
- 缓存频繁请求的数据
- 在可用时使用批处理操作
🚨 故障排除指南
常见问题及解决方案
构建失败:
# Clear cache and reinstall
rm -rf node_modules package-lock.json dist/
npm install
npm run buildAPI连接问题:
# 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桌面集成:
- 验证MCP配置语法
- 检查文件路径是否为绝对路径
- 确保环境变量已设置
- 更改后重启Claude桌面版
内存问题:
# Increase Node.js memory limit
node --max-old-space-size=8192 dist/server.jsCORS 错误:
- 配置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许可证.
______________________________________________________________________
🆘 支持与资源
文档
寻求帮助
- 查看上面的故障排除部分
- 查看Claude Desktop日志:
~/Library/Logs/Claude/mcp*.log - 验证您的私有集成API密钥和范围
- 确保所有环境变量都已正确设置
______________________________________________________________________
🎉 项目状态
✅ 250种操作工具 跨越19个类别
✅ 双服务器架构 (HTTP + 标准输入输出)
✅ 已准备好投入生产 具备全面的错误处理功能
✅ 类型安全 使用Zod模式进行验证
✅ 完整的TypeScript 带有完整的类型定义
✅ 表示“正确”或“勾选” 兼容Claude桌面版 使用MCP协议
✅ ADK代理准备就绪 通过HTTP服务器
✅ 文档齐全 带有丰富的工具描述
______________________________________________________________________
🚀 准备好自动化您的GoHighLevel工作流程了吗?
首先,按照上面的快速入门指南进行操作,配置您的私有集成API密钥,并连接您的AI代理!
______________________________________________________________________
由Cyberizegroup团队倾力打造💪,专为实现GoHighLevel的专业自动化而设计。
