ghl-mcp-remote

Remoter MCP-Server (Model Context Protocol) für GoHighLevel – multi-tenant, per URL erreichbar, damit jede Agentur ihn über Claude oder ChatGPT nutzen kann, ohne dass jede Agentur etwas lokal ausführen muss.

Dies ist ein separates Projekt zum ursprünglichen ghl-mcp (stdio, persönliche/lokale Nutzung). Keines der beiden hängt vom anderen ab.

Unterschied zum ursprünglichen ghl-mcp

Der Geschäftscode (die Tools in src/tools/) ist in beiden praktisch identisch – nur die Schicht für Authentifizierung/Speicherung ändert sich.

Related MCP server: GoHighLevel MCP Server

Architektur

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>)

• „Login“ = GHL autorisieren. Es gibt kein eigenes Konto/Passwort dieses Dienstes. Wenn der Admin einer Agentur den Zugriff auf dem Bildschirm der GHL selbst genehmigt, wird dadurch sein Tenant (identifiziert über die GHL-companyId) bereits erstellt/aktualisiert und der Login auf MCP-Seite ist abgeschlossen.

• Eine einzige GHL-Marketplace-App (gleiche GHL_CLIENT_ID/GHL_CLIENT_SECRET) bedient jede Agentur, die sie installiert – es ist nicht nötig, pro Kunde eine App zu erstellen.

• Jeder Tool-Aufruf wird authorisiert über ein Bearer-Token, das dieser Server ausstellt; die Middleware löst dieses Token zur korrekte companyId auf und injiziert es in einen AsyncLocalStorage (src/tenant-context.ts) – so bleibt der (identische) Tool-Code „ohne Bewusstsein“ für Multi-Tenancy.

• Umgesetzt auf der Grundlage dessen, was @modelcontextprotocol/sdk bereits für OAuth-Servers anbietet (server/auth/router.ts, provider.ts) – siehe src/auth/mcp-oauth-provider.ts.

Voraussetzungen für den Betrieb überall

1. GHL-Marketplace-OAuth-App (Developer > Ihre App), Vertriebsweg „Agency“ oder „Agency & Sub-Account“:

   • Redirect-URI: <PUBLIC_URL>/oauth/ghl/callback (muss die endgültige öffentliche URL – HTTPS – dieses Dienstes sein). Vor allem.

   • Scopes: die gleichen wie in src/services/scopes.ts gelistet.

2. Postgres (irgendeiner – Supabase, Neon, RDS, das verwaltete Postgres der Hosting-Plattform etc.). db/schema.sql darauf einmal ausführen.

3. Node.js 20+ (oder das Docker-Image dieses Projekts, das das seit dem enthalten hat).

Umgebungsvariablen

Siehe .env.example. Zusammenfassung:

Lokal ausführen (Dev)

npm install
npm run build
npm start

Mögliche Checks ohne eine öffentliche Domain:

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

Der vollständige OAuth-Fluss (echte Autorisierung bei der GHL, Token erhalten, ein Tool aufrufen) funktioniert nur mit einer echten PUBLIC_URL (HTTPS) im Betrieb, da die GHL den Browser des Admins der Agentur sicher hierher zurückleiten müssen muss – und dieselbe URL muss als Redirect-URI in der GHL-App registriert sein.

Deployment

Dieses Projekt setzt keine bestimmte Hosting-Plattform voraus – es enthält nur ein generisches Dockerfile. Jede Plattform, die ein Docker-Image (oder direkt node dist/index.js) betreiben kann, ist geeignet, sofern:

1. Sie eine stabile öffentliche HTTPS-URL verfügbar macht → das wird PUBLIC_URL.

2. Sie die Umgebungsvariablen aus der Tabelle oben injiziert.

3. die Postgres-Datenbank von DATABASE_URL bereits db/schema.sql ausgeführt hat.

4. die Redirect-URI der GHL-Marketplace-App auf <PUBLIC_URL>/oauth/ghl/callback gesetzt wird, sobald die endgültige URL bekannt ist.

Verbinden mit Claude / ChatGPT

Sobald gehostet:

• Claude.ai / Claude Desktop: Einstellungen → Connectors → „Custom Connector hinzufügen“ → URL: https://<deine-domain>/mcp. Claude führt Sie automatisch zum Autorisierungsablauf.

• ChatGPT: In Arbeitsbereichen mit Unterstützung für Ferne/Remote-Connectors (varriert by Plan – Team, Enterprise oder „Developer Mode“) einen Connector hinzufügen, der auf https://<deine-domain>/mcp zeigt.

Hinweis zu ChatGPT: Die Unterstützung für Remote-MCP-Connectors mit OAuth in ChatGPT ist je nach Tarif/Workspace unterschiedlich, und einige Oberflächen (z. B. Deep Research) beschränken, welche Tool-Formate sie akzeptieren (manchmal nur Tools im Format „search“/„fetch“). Dieser Server folgt der MCP-Autorisierungsspezifikation strikt (dieselbe, die Claude verwendet), was die Kompatibilität maximiert – aber es lohnt sich, ihn in echtem Betrieb zu testen, da das Verhalten auf ChatGPT-Seite außerhalb unserer Kontrolle bleibt.

Struktur

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.

Sicherheit

• GHL-Refresh-Tokens: im Ruhezustand verschlüsselt (AES-256-GCM).

• Zugriffs-/Refresh-Tokens, die dieser Server für Claude/ChatGPT ausgibt: nur als SHA-256-Hash abgelegt – niemals im Klartext, wie auch Passwörter.

• PKCE (S256) für den gesamten MCP-seitigen Ablauf verpflichtend, lokal - nicht an die GHL delegiert.

• Keine Zugangsdaten einer Agentur sind aus dem Token einer anderen agenten erreichtbar – jede Zugriff auf den Postgres wird über companyId gefiltert, und dieser Wert wird erst nach der Validierung des Bearer-Tokens eingesetzt.