Skip to main content
Glama
jamersoncalixto

ghl-mcp-remote

ghl-mcp-remote

用于 GoHighLevel 的远程 MCP(模型上下文协议)服务器 — 多租户,可通过 URL 访问,供任何机构从 Claude 或 ChatGPT 使用,而无需各自在本地运行任何东西。

这是原始 ghl-mcp(stdio,个人/本地使用)的一个独立项目。两者互不依赖。

与原始 ghl-mcp 的区别

ghl-mcp(原始)

ghl-mcp-remote(本仓库)

传输方式

stdio(本地进程)

HTTP(POST /mcp),可托管

租户

每次安装对应 1 个机构,凭据位于 ~/.ghl-mcp/credentials.json

任意数量的机构,按 companyId 隔离,凭据存储在 Postgres 中

“登录”

在终端中运行 npm run auth

GHL 自带的授权页面,由 Claude/ChatGPT 触发

使用方式

您,在本地

任何公司,通过 URL 从 Claude.ai/ChatGPT 使用

业务代码(src/tools/ 中的工具)在两个项目中几乎相同——只有认证/存储层不同。

Related MCP server: GoHighLevel MCP Server

架构

Claude/ChatGPT ──(1) descobre──> GET /.well-known/oauth-authorization-server
               ──(2) registra───> POST /register                      (DCR, automático)
               ──(3) pede login─> GET /authorize ──redirect──> tela da GHL (o "login")
                                                        <──redirect── GET /oauth/ghl/callback
               <──code+state───── (nosso próprio código de autorização)
               ──(4) troca──────> POST /token ──> access_token + refresh_token nossos
               ──(5) chama tool─> POST /mcp  (Authorization: Bearer <access_token>)
  • “登录” = 授权 GHL。 本服务没有自己的账号/密码。当机构的管理员在 GHL 自己的界面上批准访问时,就会创建/更新其租户(由 GHL 的 companyId 标识)并完成 MCP 端的登录。

  • 一个 GHL Marketplace 应用(相同的 GHL_CLIENT_ID/GHL_CLIENT_SECRET)即可服务任何安装它的机构——无需为每个客户创建应用。

  • 每次工具调用都使用此服务器签发的 Bearer token 进行身份验证;中间件将该 token 解析为正确的 companyId,并将其注入 AsyncLocalStorage(src/tenant-context.ts)——这样工具代码(与原始项目相同)就“无需感知”多租户。

  • 基于 @modelcontextprotocol/sdk 自带的 OAuth 服务器功能(server/auth/router.ts、provider.ts)实现——参见 src/auth/mcp-oauth-provider.ts。

在任何地方运行的先决条件

  1. GHL Marketplace 中的 OAuth 应用(开发者 > 您的应用),分发类型为“Agency”或“Agency & Sub-Account”:

    • 已注册的重定向 URI:<PUBLIC_URL>/oauth/ghl/callback(必须是此服务的最终公共 URL——HTTPS)。

    • 作用域:与 src/services/scopes.ts 中列出的相同。

  2. Postgres(任意一个——Supabase、Neon、RDS、托管平台自带的托管 Postgres 等)。在其上运行一次 db/schema.sql。

  3. Node.js 20+(或本项目的 Docker 镜像,已包含该环境)。

环境变量

参见 .env.example。摘要:

变量

描述

GHL_CLIENT_ID / GHL_CLIENT_SECRET

来自 GHL Marketplace 的 OAuth 应用

PUBLIC_URL

本服务的最终公共 URL,末尾不带斜杠

PORT

进程监听的端口(许多平台会自动覆盖)

DATABASE_URL

Postgres 连接字符串

TOKEN_ENCRYPTION_KEY

32 字节的 base64 编码——openssl rand -base64 32

在本地运行(开发)

npm install
npm run build
npm start

无需任何公共域名即可进行的检查:

curl localhost:8080/healthz
curl localhost:8080/.well-known/oauth-authorization-server

完整的 OAuth 流程(在 GHL 中实际授权、获取 token、调用工具)只有在存在真实的 PUBLIC_URL(HTTPS)时才能工作,因为 GHL 需要能够将机构管理员的浏览器重定向回这里——并且该 URL 必须已在 GHL 应用中注册为重定向 URI。

部署

本项目不假设任何特定的托管平台——只包含一个通用的 Dockerfile。任何能运行 Docker 镜像(或直接运行 node dist/index.js)的平台都可以,只要:

  1. 暴露一个稳定的 HTTPS 公共 URL → 这将成为 PUBLIC_URL。

  2. 注入上表中的环境变量。

  3. DATABASE_URL 指向的 Postgres 已运行过 db/schema.sql。

  4. 一旦最终 URL 确定,将 GHL Marketplace 应用的重定向 URI 更新为 <PUBLIC_URL>/oauth/ghl/callback。

连接到 Claude / ChatGPT

托管完成后:

  • Claude.ai / Claude Desktop:设置 → Connectors → Add custom connector → URL:https://<seu-dominio>/mcp。Claude 会自动带您进入授权流程。

  • ChatGPT:在支持远程 Connectors/MCP 的工作区中(因套餐而异——Team、Enterprise 或“开发者模式”),添加一个指向 https://<seu-dominio>/mcp 的连接器。

关于 ChatGPT 的注意事项:ChatGPT 对带 OAuth 的远程 MCP 连接器的支持因套餐/工作区而异,某些界面(例如 Deep Research)会限制接受的工具格式(有时只接受“search”/“fetch”格式的工具)。本服务器严格遵守 MCP 的授权规范(与 Claude 使用的相同),从而最大限度地提高兼容性——但托管后还是值得实际测试一下,因为 ChatGPT 端的行为不在我们的控制范围内。

结构

src/
  index.ts                 App Express: monta o router de OAuth, POST/GET/DELETE /mcp,
                            GET /oauth/ghl/callback, GET /healthz, CORS.
  server.ts                 createMcpServer() — registra as tools (idêntico ao projeto original).
  tenant-context.ts          AsyncLocalStorage que carrega o companyId durante cada request.
  db/
    pool.ts                  Pool do `pg` a partir de DATABASE_URL.
    crypto.ts                 AES-256-GCM (tokens da GHL em repouso) + SHA-256 (hash dos nossos tokens).
    agencies.ts                Tokens de agência da GHL por companyId (substitui o antigo token-store.ts).
    oauth-store.ts              Clients MCP, pending auth, authorization codes, access/refresh tokens.
  auth/
    ghl-oauth.ts               Troca/refresh de tokens com a GHL — equivalente ao oauth-flow.ts original,
                               mas web-based e por tenant em vez de CLI + arquivo único.
    location-tokens.ts          Cache de location tokens, agora chaveado por companyId.
    mcp-oauth-provider.ts        Implementa OAuthServerProvider do SDK — o núcleo do "login = autorizar a GHL".
    ghl-callback.ts               Handler de GET /oauth/ghl/callback.
  services/
    constants.ts, scopes.ts, ghl-client.ts   Idênticos ao projeto original (só o import de token mudou).
  tools/
    *.ts                       Idênticos ao projeto original, exceto locations.ts (cache agora por tenant).
db/
  schema.sql                  DDL do Postgres — rodar uma vez antes do primeiro start.

安全

  • GHL 刷新令牌:静态加密(AES-256-GCM)。

  • 此服务器为 Claude/ChatGPT 签发的访问/刷新令牌:仅以 SHA-256 哈希形式存储——绝不使用明文,与密码相同。

  • 在 MCP 端的整个流程中强制要求 PKCE(S256),并在本地验证(不委托给 GHL)。

  • 任何机构的凭据都无法通过另一机构的令牌访问——所有对 Postgres 的访问都通过 companyId 过滤,并且该值只有在 Bearer token 验证通过后才会生效。

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    MCP server for GoHighLevel API v2 that provides 50+ tools for CRM, billing, marketing, and operations workflows, enabling natural language interaction with contacts, opportunities, conversations, and more.
    50
    1
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for GoHighLevel sub-accounts, enabling management of CRM contacts, pipelines, calendars, invoices, and more via natural language.
    -