ghl-mcp-server

GHL MCP 服务

面向 Claude、N8N 和自定义 AI Agent 的 GoHighLevel MCP 服务 由 Saurabh K Shah 构建（https://saurabhshah.com）

一款功能全面的模型上下文协议（MCP）服务，可将 AI 助手直接连接到你的 GoHighLevel CRM。支持 60+ 种工具，涵盖联系人、对话、日历、销售管道、付款、发票、工作流、自定义字段、社交媒体等。

功能

• 联系人：搜索、创建、更新、删除、插入或更新联系人，管理标签、备注、任务和工作流
• 对话与消息：SMS、Email、WhatsApp，搜索对话线程、发送消息、安排发送时间
• 日历与预约：列出日历、获取空闲时段、创建／更新／删除事件
• 商机与销售管道：完整的交易管理、阶段转换、销售管道列表
• 付款与发票：订单、交易、订阅，以及创建／发送／作废发票
• 工作流：列出所有工作流，将联系人添加到工作流或从中移除
• 自定义字段：列出和创建联系人自定义字段
• 位置：子账户详情、标签管理
• 用户：搜索团队成员
• 表单与调查：列出表单／调查、获取提交记录
• 营销活动：列出所有营销活动
• 社交媒体：列出／创建帖子，查看已连接的账户
• 漏斗与博客：列出漏斗和博客
• 产品：列出产品和价格

快速开始

1. 获取 GHL 凭据

1. 登录 GoHighLevel → 设置 → Private Integrations
2. 点击 Create New Integration
3. 为其命名（例如，“Claude MCP Server”）
4. 选择所需的所有权限范围（联系人、对话、日历、付款等）
5. 复制 Private Integration Token
6. 记下你的 Location ID（查看任何子账户时显示在 URL 中）

2. 安装和配置

git clone https://github.com/northrosetech/ghl-mcp-server.git
cd ghl-mcp-server
npm install
cp .env.example .env

编辑 .env：

GHL_API_KEY=your_private_integration_token_here
GHL_LOCATION_ID=your_location_id_here

构建：

npm run build

3. 连接到 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（Mac 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "your_private_integration_token",
        "GHL_LOCATION_ID": "your_location_id",
        "TRANSPORT": "stdio"
      }
    }
  }
}

重启 Claude Desktop。此时应能看到可用的 GHL 工具。

4. 连接到 N8N（HTTP 模式）

以 HTTP 模式启动服务：

TRANSPORT=http PORT=3001 GHL_API_KEY=your_token GHL_LOCATION_ID=your_id node dist/index.js

在 N8N 中：

1. 添加 MCP Client 节点
2. 将 URL 设置为 http://localhost:3001/mcp
3. 将传输方式设置为 HTTP Streamable
4. 在工作流中使用 GHL 工具

5. 连接到 Claude Code

将以下内容添加到项目的 .mcp.json：

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["./ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "your_token",
        "GHL_LOCATION_ID": "your_id"
      }
    }
  }
}

可用工具（60+）

联系人（15 个工具）

工具	描述
ghl_search_contacts	按查询词、标签和筛选条件搜索联系人
ghl_get_contact	按 ID 获取联系人
ghl_create_contact	创建新联系人
ghl_update_contact	更新现有联系人
ghl_delete_contact	删除联系人
ghl_upsert_contact	按邮箱／电话创建或更新联系人
ghl_add_contact_tags	为联系人添加标签
ghl_remove_contact_tags	移除联系人的标签
ghl_get_contact_notes	获取联系人备注
ghl_create_contact_note	为联系人添加备注
ghl_delete_contact_note	删除备注
ghl_get_contact_tasks	获取联系人任务
ghl_create_contact_task	为联系人创建任务
ghl_update_contact_task	更新任务
ghl_add_contact_to_workflow	将联系人添加到工作流
ghl_remove_contact_from_workflow	将联系人从工作流中移除

对话与消息（6 个工具）

工具	描述
ghl_search_conversations	搜索对话线程
ghl_get_conversation	获取对话详情
ghl_get_messages	获取线程中的消息
ghl_send_message	发送 SMS／Email／WhatsApp 等消息
ghl_cancel_scheduled_message	取消已安排的消息
ghl_update_conversation	更新对话状态

日历与预约（8 个工具）

工具	描述
ghl_list_calendars	列出所有日历
ghl_get_calendar	获取日历详情
ghl_get_free_slots	获取可预约时段
ghl_get_events	获取预约／事件
ghl_create_event	创建预约
ghl_update_event	更新预约
ghl_delete_event	删除预约
ghl_create_calendar	创建新日历

商机与销售管道（7 个工具）

工具	描述
ghl_search_opportunities	搜索交易
ghl_get_opportunity	获取交易详情
ghl_create_opportunity	创建新交易
ghl_update_opportunity	更新交易／移动阶段
ghl_delete_opportunity	删除交易
ghl_update_opportunity_status	更改交易状态
ghl_list_pipelines	列出销售管道与阶段

付款与发票（9 个工具）

工具	描述
ghl_list_orders	列出付款订单
ghl_get_order	获取订单详情
ghl_list_transactions	列出交易记录
ghl_list_subscriptions	列出订阅
ghl_list_invoices	列出发票
ghl_get_invoice	获取发票详情
ghl_create_invoice	创建发票
ghl_send_invoice	通过电子邮件向联系人发送发票
ghl_void_invoice	作废发票

其他工具（15 个以上工具）

工具	描述
ghl_list_workflows	列出所有工作流
ghl_list_custom_fields	列出自定义字段
ghl_create_custom_field	创建自定义字段
ghl_get_location	获取位置详情
ghl_get_location_tags	获取位置标签
ghl_create_location_tag	创建新标签
ghl_search_users	搜索团队成员
ghl_list_forms	列出表单
ghl_get_form_submissions	获取表单提交记录
ghl_list_surveys	列出调查问卷
ghl_list_campaigns	列出营销活动
ghl_list_social_posts	列出社交媒体帖子
ghl_create_social_post	创建／安排社交媒体帖子
ghl_list_social_accounts	列出已连接的社交媒体账号
ghl_list_funnels	列出漏斗／网站
ghl_list_products	列出产品
ghl_list_blogs	列出博客
ghl_list_links	列出触发链接

架构

ghl-mcp-server/
├── src/
│   ├── index.ts              # Entry point (stdio + HTTP transport)
│   ├── constants.ts          # All GHL API endpoints & config
│   ├── types.ts              # TypeScript interfaces
│   ├── services/
│   │   └── api-client.ts     # Auth, rate limiting, error handling
│   └── tools/
│       ├── contacts.ts       # Contact management tools
│       ├── conversations.ts  # Messaging tools
│       ├── calendars.ts      # Calendar & appointment tools
│       ├── opportunities.ts  # Pipeline & deal tools
│       └── business.ts       # Payments, invoices, workflows, etc.
├── dist/                     # Compiled JS
├── package.json
├── tsconfig.json
└── .env.example

速率限制

该服务内置了与 GHL 限制相匹配的速率限制：

• 突发请求：每 10 秒 100 个请求
• 每日请求：每天 200,000 个请求

接近限制时，服务会自动将请求排队并重试。

错误处理

所有工具都会返回可执行的错误信息及提示：

• 401：检查你的 API 密钥（必须是 Private Integration Token）
• 403：缺少权限范围——在 GHL Settings 中编辑你的 Private Integration
• 404：未找到资源——检查 ID
• 422：验证错误，包含详细信息
• 429：速率限制——自动重试

许可证

MIT — 由 Saurabh K Shah 构建（https://saurabhshah.com）