ghl-context-mcp

一个刻意保持精简的 GoHighLevel MCP 服务器。六种工具，只专注一件事：让你在打电话之前，心里有数对面是谁。

为什么会有它

在 CRM 之上接入一个智能体，最常见的失败模式是暴露一块又宽又泛的工具面，把原始 API JSON 直接倒出来：模型会选择错误的工具，把上下文窗口烧在那些没有出人会说出口的字段上，偶尔还捏造或覆盖一条记录。这台服务器选的是另一个方向。它只提供六个工具，每个工具都对上一次与联系人交谈的那个时刻。它返回出的每个字段，要么是别人会说出口的话，要么是别人下一次调用时需要传回去的东西。日期计算它自己做，写入功能则在点亮之前始终关闭。窄工具面是否真的胜过宽工具面，这是可衡量的；配套的基准 mc-tool-suface-bench 就是用来量它的。

Related MCP server: GHL MCP Server

工具

上限是每次响应的 token 预算，它由一个测试强制保证：如果响开始超过上限，构建就会失败。这里“token”差不多，见 DESIGN.md。

使用方法

这是一个 MCP 服务器，目标用户是 AI 智能体，而不是坐在终端前的人。你需要把服务器接到你的智能体上（Claude Code、Claude Desktop 或任何支持 MCP 的运行时），然后用直观语言和智能体对话。解析联系人、拉取上下文，这部分交给智能体自己决定。

团队快速开始：Claude Code

1. 克隆代码库，然后安装并构建：

npm install && npm run build

2. 加入你的凭据：

cp .env.example .env
# then edit .env and fill in GHL_PIT and GHL_LOCATION_ID

3. 在 Claude Code 中打开对应文件夹。它会读取已检入的 .mcp.json，提示你 ghl-context 服务器存在，你只需批准一次。服务器在启动时自动加载 .env，所以没有 token 会落在配置文件里。

4. 用销售代表在开始一天工作时的方式对你的智能体说话：

   我今天要给 Marcus Halloway 和 Priya Nair 打电话。在每位接线之前，给我一份通话前简报。

智能体会解析每个联系人，拉去时间线、管道位置、快到来的约会，并给你汇报。

其他 MCP 客户端

任何 MCP 客户端都可以通过 stdio 连接这个服务器。发布版不需要普通体，也不需要构建。使用 Claude Desktop 时，往 claude_desktop_config.json 里加入这段配置：

{
  "mcpServers": {
    "ghl-context": {
      "command": "npx",
      "args": ["-y", "ghl-context-mcp"],
      "env": {
        "GHL_PIT": "pit-...",
        "GHL_LOCATION_ID": "your-sub-account-id"
      }
    }
  }
}

如果想使用本地代码，而不是发布版，请把 command 设为 node，把 args 指向你构建好的 dist/index.js。

环境变量

在 Settings、Integrations、Private Integrations 下创建这个 token，信域选中 contacts.readonly、contacts.write、opportunities.readonly、opportunities.wite 和 calendars.readonly。

没有客户端也先看到并且效果

如果手边没有 MCP 客户端，代码库里带了一个终端 demo，它会跑跟智能体几乎完全相同操作步骤，然后打印走那会前现场：

npm run brief -- "Marcus Halloway"

它不是最终产品，只是证明“这套做法有价值”的演示。最终产品，是上面那个智能体连接。

从源码运行

npm install
npm run build
npm test

npm test，在没有任何凭据的情况下，也要能构建通过。在线检查 npm run live-check 和 npm run live-write-check，需要一份真实的。

响应结构

一份能解析出来的联系人：

{
  "resolution": "exact",
  "contact": {
    "contact_id": "NnAyKFnTSAVKg1amAArO",
    "name": "Marcus Halloway",
    "primary_phone": "+15551230010",
    "primary_email": "marcus.halloway@example.com",
    "tags": ["synthetic-seed"],
    "owner": null,
    "last_activity_at": null,
    "last_activity_summary": null
  }
}

一个不精确匹配时返回候选项，而不是去猜：

{
  "resolution": "ambiguous",
  "candidates": [
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230012",
      "primary_email": "jordan.wells@example.com",
      "last_activity_at": null
    },
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230013",
      "primary_email": "jordan.wells.cpa@example.com",
      "last_activity_at": null
    }
  ],
  "disambiguate_by": ["email", "primary_phone"],
  "instruction": "Ask the user which one, or call again with the exact email or phone."
}

出现不清晰，我们算成功。智能体遇到报从一开始会停止；拿到了候选项列表的智能体，会继续往下走並问你“你指的是哪一位”。

错误

所有错误都是同一种形态，原始 HTTP 状态码不会直接进到模型。

设计笔记

这条服务器建立在八条规则上，这里每条一句话。完整版、以及预期间里面会出现那“过了未知”式问答的推演，在 DESIGN.md。

1. 一把工具只做一件事。如果工具描述落得需要写“实现”，说明这是两个工具。

2. 描述是写给模型看的：它什么时候应该用它、不要用它，以及它和哪个兄弟工具容易搞混。

3. 原始的 API 数据形态不得越过该边界，有测试强制。

4. 错误是指令式的，使用祈对语气写，并列出它现在该选哪些合法选项。

5. 每个响应都带 token 上限，有测试强制，超出就会导致构建失败。

6. 服务器本身完成算术：年龄、时长、相对时间、次数计算都是在它计算。

7. 写操作只会基础上它们所依赖的状态发生变化上执行，如果状态不一致，就会大声失败。

8. 写入默认关着，只有 GHL_ALLOW_WRITES=true 才开。

一切它不做的事

这些“不做”都是留有余地。

局限

只支持单个 location、只有 Private Integration Token 认证，不支持 OAuth。分项有上限：每工具可取的列表数量固定。停滞检测需要有一定规模的数据才有意义，写在出来的代码中目前用了一个定值兜底，原因是 GoUpLevel 不暴露阶段历史。电话号匹配是 North America 为中心的。Token 限上是代理 token 计，不是 Claude 原生 token 计。GoHighLevel 的读取比写入慢大概 1 秒。目前的测试只验证一个“账号形状应样本”。

许可证

MIT