ghl-mcp-remote

GoHighLevel 用のリモート MCP (Model Context Protocol) サーバー — マルチテナント、URL 経由でアクセス可能。Claude や ChatGPT からどのエージェンシーでも使用でき、各社がローカルで何かを実行する必要はありません。

これは元の ghl-mcp (stdio、個人/ローカル使用) とは別のプロジェクトです。どちらも互いに依存していません。

元の ghl-mcp との違い

ビジネスコード (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 トークンで認証されて届きます。ミドルウェアはそのトークンを正しい 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 アプリ (Developer > あなたのアプリ)、配布形態は「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 を参照してください。まとめ:

ローカルでの実行 (開発)

npm install
npm run build
npm start

公開ドメインなしで可能な確認:

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

完全な OAuth フロー (実際に GHL で認可し、トークンを取得し、ツールを呼び出す) は、実際の 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、または「Developer mode」) で、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 ハッシュとしてのみ保存 — パスワードと同様、平文では決して保存しません。

• PKCE (S256) は MCP 側のすべてのフローで必須であり、ローカルで検証されます (GHL に委任されません)。

• あるエージェンシーの資格情報は、別のエージェンシーのトークンからはアクセスできません — Postgres へのすべてのアクセスは companyId でフィルタリングされ、その値は Bearer トークンが検証された後にのみ登場します。