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 installed
Maintenance
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
- 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.2135MIT
- 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.1001935MIT
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.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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