@aiwerk/mcp-server-ghl

用于 GoHighLevel (GHL) API 的 MCP 服务器，该平台是代理商用来管理客户销售管道、日历、对话和活动的 CRM 和营销自动化平台。

569 个工具，涵盖 41 个域，根据 GHL 官方 OpenAPI 3.0.0 规范生成。

Contacts       Opportunities   Conversations   Calendars      Invoices
Payments       Workflows       Campaigns       Forms          Surveys
Funnels        Blogs           Courses         Products       Store
Social Media   Ad Manager      SaaS API        Snapshots      Custom Fields

为什么生成

每个端点、HTTP 动词、参数和字段名都来自官方规范，而不是散文式文档，因此工具表面不会偏离 GHL 实际接受的内容。规范无法告诉你的内容——哪些端点需要机构级令牌而不是位置级令牌、端点期望哪个 API 版本、文档忘记标记为必填的字段——都是手工叠加的。参见 值得了解的 GHL 细节。

Related MCP server: GoHighLevel MCP Server

安装

npm install -g @aiwerk/mcp-server-ghl

需要 Node.js 18 或更高版本。

身份验证

在目标位置的 设置 > 私有集成 下创建 私有集成令牌 (PIT)。PIT 仅限一个位置，它不是机构范围的凭据，大多数工具需要知道它们正在操作哪个位置。

export GHL_PIT_TOKEN="your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"

用法

Claude Code

claude mcp add ghl \
  --env GHL_PIT_TOKEN=your-token \
  --env GHL_LOCATION_ID=your-location-id \
  -- npx -y @aiwerk/mcp-server-ghl

Claude Desktop

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-ghl"],
      "env": {
        "GHL_PIT_TOKEN": "your-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

AIWerk 托管服务

从 aiwerkmcp.com 的目录中安装它，并在界面中添加你的令牌。无需本地设置。

安全功能

试运行

export GHL_DRY_RUN=1

每次写入（POST/PUT/PATCH/DELETE）在到达 GHL 之前都会被阻止，并返回本应发送的请求的描述。读取仍然正常工作。

仅限机构的端点会返回明确的错误，而不是裸 401

39 个端点（快照、SaaS API、机构 OAuth 令牌交换、创建自定义对象）需要机构级令牌。位置 PIT 从 GHL 获得这些端点的普通 401，响应体中没有解释，服务器知道这些端点是什么，并返回一条说明此情况的消息，而不是让它看起来像令牌错误或过期。

locationId 自动填充

PIT 已经限定在一个位置，因此 569 个工具中有 430 个接受 locationId（或 altId/altType）作为 可选 参数，如果调用代理未提供，服务器会回退到 GHL_LOCATION_ID。这也意味着工具调用不会因为从其他账户复制粘贴的 id 而意外定位到错误的位置，因为默认值始终与令牌自身的范围匹配。

配置

缩小工具集

默认情况下，所有 569 个工具都已注册。喜欢较小表面的客户端可以将服务器限制为特定域（域名用连字符连接，例如 social-media-posting、ad-manager）：

export GHL_ENABLED_TAGS="contacts,opportunities,conversations,calendars"

未知域名会在启动时报告，而不是被静默忽略。

一些值得了解的 GHL 细节

• API 版本因端点而异，而非全局统一。 GHL 发送一个 Version 请求头（2021-07-28 或 2021-04-15），服务器根据每个端点实际期望的内容为每次调用设置该头，错误的版本会静默返回 不同的响应形状，而不是错误，因此没有单一的默认值可回退。29 个端点根本不发送版本头；服务器也会匹配这一点。

• 位置 PIT 永远无法调用仅限机构的端点，任何范围都无法解决。 snapshots/*、saas-api/*、oauth/locationToken、oauth/installedLocations 以及创建自定义对象（POST /objects）需要机构级凭据。

• 官方规范中的 11 个端点省略了路径参数的声明（例如某些日历/对话路由上的 noteId、博客上的 postId、联系人上的 type）。生成器将这些填充为必需的字符串字段，因为该参数显然在路径模板中使用，这是上游规范的缺口，而不是此处引入的问题。

• 速率限制尚未针对真实账户进行测量。 客户端在 429 时使用 GHL 发送的任何 Retry-After 进行重试，但不会用虚构的数字进行预防性限流，错误的假设限制要么会低估账户的使用，要么会导致本应成功的调用失败。

测试

npm test          # unit tests, mocked fetch
npm run smoke      # read only, against a live account

开发

工具层是生成的，不得手动编辑：

npm run gen-naming   # specification  ->  tool names
npm run gen-tools    # specification  ->  zod schemas and call sites
npm run build

许可证

MIT，参见 LICENSE。

由 AIWerk 构建。与 GoHighLevel / HighLevel Inc. 无关联。