ghl-mcp-remote

Удалённый MCP-сервер (Model Context Protocol) для GoHighLevel — multi-tenant, доступный по 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, это уже создаёт/обновляет его арендатора (идентифицируемого по companyId из GHL) и завершает вход на стороне MCP.

• Одно приложение GHL Marketplace (тот же GHL_CLIENT_ID/GHL_CLIENT_SECRET) обслуживает любое агентство, которое его установит — не нужно создавать приложение для каждого клиента.

• Каждый вызов инструмента приходит аутентифицированным с Bearer-токеном, выпущенным этим сервером; middleware разрешает этот токен до нужного companyId и внедряет это в AsyncLocalStorage (src/tenant-context.ts) — именно так код инструментов (идентичный коду оригинального проекта) остаётся «не знающим» о multi-tenancy.

• Реализовано на основе того, что сам @modelcontextprotocol/sdk уже предоставляет для OAuth-серверов (server/auth/router.ts, provider.ts) — см. src/auth/mcp-oauth-provider.ts.

Предварительные требования для запуска где угодно

1. OAuth-приложение в GHL Marketplace (Developer > ваше приложение), распространение «Agency» или «Agency & Sub-Account»:

   • Зарегистрированный Redirect URI: <PUBLIC_URL>/oauth/ghl/callback (должен быть окончательным публичным URL этого сервиса — HTTPS).

   • Scopes: те же, что перечислены в src/services/scopes.ts.

2. Postgres (любой — Supabase, Neon, RDS, управляемый Postgres самой хостинг-платформы и т.д.). Выполнить db/schema.sql на нём один раз.

3. Node.js 20+ (или Docker-образ этого проекта, который уже включает это).

Переменные окружения

См. .env.example. Кратко:

Запуск локально (dev)

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 должен быть зарегистрирован как redirect URI в приложении GHL.

Развёртывание

Этот проект не предполагает конкретную хостинг-платформу — он просто включает универсальный Dockerfile. Любая платформа, которая запускает Docker-образ (или node dist/index.js напрямую), подойдёт, при условии:

1. Предоставляет стабильный публичный HTTPS URL → он становится PUBLIC_URL.

2. Внедряет переменные окружения из таблицы выше.

3. Postgres, указанный в DATABASE_URL, уже выполнил db/schema.sql.

4. Redirect URI приложения GHL Marketplace обновлён на <PUBLIC_URL>/oauth/ghl/callback как только окончательный URL станет известен.

Подключение к Claude / ChatGPT

После размещения:

• Claude.ai / Claude Desktop: Настройки → Connectors → Add custom connector → URL: https://<ваш-домен>/mcp. Claude автоматически проведёт вас через поток авторизации.

• ChatGPT: в рабочих пространствах с поддержкой Connectors/удалённого MCP (зависит от тарифа — Team, Enterprise или «Developer mode»), добавьте connector, указывающий на https://<ваш-домен>/mcp.

Предостережение о ChatGPT: поддержка удалённых MCP-коннекторов с OAuth в ChatGPT зависит от тарифа/рабочего пространства, и некоторые поверхности (например, 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.

Безопасность

• Refresh-токены GHL: зашифрованы в состоянии покоя (AES-256-GCM).

• Access/refresh-токены, которые этот сервер выдаёт для Claude/ChatGPT: хранятся только как хэш SHA-256 — никогда в открытом виде, как пароль.

• PKCE (S256) обязателен во всём потоке на стороне MCP, проверяется локально (не делегируется GHL).

• Никакие учётные данные одного агентства недоступны по токену другого — весь доступ к Postgres фильтруется по companyId, и это значение вступает в игру только после того, как Bearer-токен проверен.