使用说明

🚀 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_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"

🔧 开发与测试

可用脚本

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 build

API连接问题：

# 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.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的专业自动化而设计。