ghl-mcp-remote
ghl-mcp-remote
用于 GoHighLevel 的远程 MCP(模型上下文协议)服务器 — 多租户,可通过 URL 访问,供任何机构从 Claude 或 ChatGPT 使用,而无需各自在本地运行任何东西。
这是原始 ghl-mcp(stdio,个人/本地使用)的一个独立项目。两者互不依赖。
与原始 ghl-mcp 的区别
|
| |
传输方式 | stdio(本地进程) | HTTP( |
租户 | 每次安装对应 1 个机构,凭据位于 | 任意数量的机构,按 |
“登录” | 在终端中运行 | 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。
在任何地方运行的先决条件
GHL Marketplace 中的 OAuth 应用(开发者 > 您的应用),分发类型为“Agency”或“Agency & Sub-Account”:
已注册的重定向 URI:
<PUBLIC_URL>/oauth/ghl/callback(必须是此服务的最终公共 URL——HTTPS)。作用域:与
src/services/scopes.ts中列出的相同。
Postgres(任意一个——Supabase、Neon、RDS、托管平台自带的托管 Postgres 等)。在其上运行一次
db/schema.sql。Node.js 20+(或本项目的 Docker 镜像,已包含该环境)。
环境变量
参见 .env.example。摘要:
变量 | 描述 |
| 来自 GHL Marketplace 的 OAuth 应用 |
| 本服务的最终公共 URL,末尾不带斜杠 |
| 进程监听的端口(许多平台会自动覆盖) |
| Postgres 连接字符串 |
| 32 字节的 base64 编码—— |
在本地运行(开发)
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)的平台都可以,只要:
暴露一个稳定的 HTTPS 公共 URL → 这将成为
PUBLIC_URL。注入上表中的环境变量。
DATABASE_URL指向的 Postgres 已运行过db/schema.sql。一旦最终 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 验证通过后才会生效。
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP 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.501MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that provides tools for managing GoHighLevel (GHL) conversations, tasks, and calendar appointments through AI assistants like Claude.2173 npmMIT
- FlicenseNot gradedqualityDmaintenanceMCP server for GoHighLevel sub-accounts, enabling management of CRM contacts, pipelines, calendars, invoices, and more via natural language.-
- AlicenseCqualityAmaintenanceA Model Context Protocol (MCP) server for GoHighLevel API v2 — giving any AI agent full access to your GHL location.10015 npm6MIT