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,并将其注入 AsyncLocalStoragesrc/tenant-context.ts)——这样工具代码(与原始项目相同)就“无需感知”多租户。

  • 基于 @modelcontextprotocol/sdk 自带的 OAuth 服务器功能(server/auth/router.tsprovider.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 验证通过后才会生效。

F
license - not found
Not graded
quality - not tested
B
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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.

View all related MCP servers

Related MCP Connectors

  • Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.

  • Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.

  • MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jamersoncalixto/ghl-mcp-remote'

If you have feedback or need assistance with the MCP directory API, please join our Discord server