GoHighLevel MCP Server

一个 Model Context Protocol 服务器，让 LLM 智能体能够对 GoHighLevel CRM 进行操作控制——在 24 个模块中提供 114 个工具，涵盖联系人、销售管道、日历、消息、开票与支付，全部基于 GoHighLevel API v2。

问题

GoHighLevel 是一家小型代理机构的记录系统：每一位客户、每一次预订、每一张发票。真正消耗一整天的不是某个独立的 CRM 操作，而是它们之间的衔接——一次拍摄确认了，于是就得有人创建商机、把它移动到正确的销售管道阶段、针对正确的联系人预订日历时段、起草发票，并记录一条备注。每一步都只需要五十秒的点击，而这套流程每周要跑好几遍。

这套流程正是智能体擅长做的事——只要它能触达 CRM。本服务器就是那个「触达」：它把 GoHighLevel 暴露为一组有类型、带注解的工具，让智能体只凭一句话的指令就能走完整条链路，同时让破坏性和面向外部的步骤仍然保留为可审批的环节。

Related MCP server: GoHighLevel MCP Server

架构

24 个工具模块通过 stdio 注册到一个 McpServer 上。所有流量都经由一个独立的 ghlRequest() 路由，它负责认证、强制要求的 Version 头部、查询字符串组装以及错误整形。模块可以通过 GHL_DISABLED_MODULES 在启动时切换开关——它的重要性比听上去要大得多：因为 114 个工具定义本身就占据智能体上下文窗口的相当一部分，而这还发生在它读到用户请求的第一个字之前。一个只涉及预订的部署可以只注册六个模块，跳过其余所有。

  MCP host (Claude Desktop / Claude Code)
          | stdio (JSON-RPC)
  +-------v--------------------------------------------+
  |  index.ts   MODULES registry, GHL_DISABLED_MODULES  |
  +-------+--------------------------------------------+
          |
  +-------v-----+ +---------------+ +-----------+ ......  24 modules
  |  contacts   | | opportunities | | invoices  |
  +-------+-----+ +-------+-------+ +-----+-----+
          |               |               |
          |               |         +-----v--------------+
          |               |         | billing-helpers.ts |
          |               |         |  businessDetails   |
          |               |         |  contactDetails    |
          |               |         |  sender resolution |
          |               |         +-----+--------------+
          +-------+-------+---------------+
                  |
        +---------v----------------------------+
        |  client.ts  ghlRequest()             |
        |   Bearer token + Version header      |
        |   status-specific error hints        |
        +---------+----------------------------+
                  |
          services.leadconnectorhq.com

每个写入工具都带有 MCP 注解；其中 17 个被标为 destructiveHint，另外 ghl_send_message 和 ghl_send_invoice 被标记为面向外部，因为它们会接触真实客户。宿主在批准调用之前会先把这些标注呈现出来，这正是「一个替你起草发票的智能体」与「一个不小心把发票‘群发’出去给客户的智能体」之间的区别。

真正难的蛋糕

创建发票。端点接收 businessDetails 和 contactDetails 两个块，而文档对两者的描述都远远不足：如果按文档说的那样传一个 contactId 和几个明细行，那么你会得到一个不涉及任何字段名称的校验错误。两个块都必须完整给出，而且 businessDetails.phoneNo 和 contactDetails.phoneNo 是强制的————一个只有电子邮箱、没有手机号的联系人，根本无法开票。

更糟的是，这些值必须和 UI 输出的 完全一致，否则通过 API 创建的发票会和手工创建的发票看起来不一样——不同的 logo、缺失的条款、凌乱的编号。这些默认值并不在你以为能找到它们的位置配置（location profile）中，而是藏在 GET /invoices/settings 背后，而这个接口正是 UI 预填时使用的同一个数据源。

src/tools/billing-helpers.ts 把两个块的内容都解析好，让工具只需要一个 contactId 即可。企业信息按四级回退：单个调用参数 → GHL_BUSINESS_* 环境变量 → 已保存的发票设置 → 位置配置文件，每一层只负责补上上一层留空的部分。联系人信息则抓取后组装，name 按回退顺序取全名 → 姓+名 → 公司名称 → 邮箱 → 电话，因为 GoHighLevel 会拒绝空名字，而真实 CRM 记录里经常缺名字。两条路径都会在缺字段时抛出「字段名 + 如何补充」的提示，而不是直接暴露 GHL 不透明的 422。每次查找都会按 location 做记忆化（memoised），所以一次批量开十张发票只触发一次设置读取，而不是十次。

我会有不用的做法的地方

1. 完全没有测试。 大约 4000 行代码、零测试。billing-helpers 里的回退链是对 fixture 数据做纯逻辑操作——这是整个仓库里最好测的东西，也是出错成本最高的部分，失败模式就是一张畸形的发票直接被发给了最终客户。

2. 429 之后没有重试。 ghrRequest 会告诉调用方「已限流，请稍后重试」，然后真就不重试了。退避应该在客户端实现，而不应该由智能体做判断。

3. 缓存是模块级的可变 map，而且没有失效机制。 对宿主能随意重启的 stdio 服务器来说这是正确的；但一旦这个进程是长生命周期的服务，就错了——因为企业资料的编辑永远不会被这个缓存感知到。

4. 响应到处都是 Record<string, unknown>。 GoHighLevel 发布了 OpenAPI 规范；按规范生成类型，可以把一类本来在运行时爆出来的意外变成编译期错误。

5. 一个服务器塞进 114 个工具太多了。 模块开关只是 workaround，不是修复。更好的形态是一小组基础工具加一个「发现」机制，让智能体按需商会它所实际需要的东西。

配置

需要 Node.js 20+ 以及 GoHighLevel 账户。

1. 创建 Private Integration（私有集成）令牌

Settings → Private Integrations → Create new integration。勾选要与你要用的工具匹配的权限范围；最少包括：

contacts.readonly，contacts.write， opportunities.readonly， opportunities.write， calendars.readonly， calendars/events.write， conversations.readonly， conversations/message.write， invoices.readonly（仅发票）， invoices.write ， products.readonly， products.write， locations/customFields.readonly ， workflows.readonly

复制令牌——它以 pit- 开头。

2. 找到你的 Location ID

Settings → Business Profile，或者从 Dashboard 地址栏读出来：：.../location/<LOCATION_ID>/...

3. 构建

git clone <this-repo>
cd ghl-mcp
npm install
npm run build

4. 注册到某个 MCP 宿主

{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

重启宿主。所有支持的变量见 .env.example，包括发票的 business 块以及模块开关。

要绕过宿主来验证这个服务：

GHL_API_KEY=pit-... GHL_LOCATION_ID=... npm run inspect

关于「构建自动化」的说明

GoHighLevel 的 API 不能创建 工作流的逻辑——可视化编辑器只能在 UI 里使用。推荐的做法是：先在 UI 中把工作流建好，然后用 ghl_list_workflows 找到这个工作流 id，再用 ghl_add_contact_to_workflow 把联系人加入工作流。

工具参考

许可证

MIT——见 LICENSE。本项目与 GoHighLevel 既无关联，也是未被其认可。