ghl-mcp-remote

GoHighLevel용 원격 MCP(Model Context Protocol) 서버 — 멀티 테넌트이며, URL을 통해 접근할 수 있습니다. 각 에이전시가 로컬에서 아무것도 실행할 필요 없이 Claude 또는 ChatGPT에서 사용할 수 있습니다.

이 프로젝트는 원래의 ghl-mcp (stdio, 개인/로컬용)와 별개의 프로젝트입니다. 둘 중 어느 것도 다른 하나에 의존하지 않습니다.

원래 ghl-mcp와의 차이점

비즈니스 코드(src/tools/의 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)으로 그 앱을 설치하는 모든 에이전시를 처리합니다. 클라이언트별로 앱을 만들 필요가 없습니다.

• 모든 tool 호출은 이 서버가 발급한 Bearer 토큰으로 인증되어 도착합니다. 미들웨어는 해당 토큰을 올바른 companyId로 해석하고 이를 AsyncLocalStorage(src/tenant-context.ts)에 주입합니다 — 이렇게 해서 (원래 프로젝트와 동일한) tools 코드가 멀티 테넌시를 "알지 못한 채" 유지됩니다.

• @modelcontextprotocol/sdk가 OAuth 서버용으로 이미 제공하는 것 위에 구현되었습니다(server/auth/router.ts, provider.ts) — src/auth/mcp-oauth-provider.ts 참조.

어디서든 실행하기 위한 사전 요구사항

1. GHL Marketplace의 OAuth 앱(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 참조. 요약:

로컬에서 실행 (개발)

npm install
npm run build
npm start

공개 도메인 없이도 가능한 확인:

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

전체 OAuth 흐름(실제로 GHL에서 승인하고, 토큰을 받고, tool을 호출하는 것)은 실제 PUBLIC_URL(HTTPS)이 올라와 있어야만 작동합니다. GHL이 에이전시 관리자의 브라우저를 다시 여기로 리디렉션할 수 있어야 하고, 동일한 URL이 GHL 앱에 redirect URI로 등록되어 있어야 하기 때문입니다.

배포

이 프로젝트는 특정 호스팅 플랫폼을 가정하지 않습니다 — 그저 범용 Dockerfile을 포함할 뿐입니다. Docker 이미지를 실행할 수 있는(또는 node dist/index.js를 직접 실행하는) 모든 플랫폼이 다음 조건만 충족하면 됩니다:

1. 안정적인 공개 HTTPS URL을 노출합니다 → 이것이 PUBLIC_URL이 됩니다.

2. 위 표의 환경 변수를 주입합니다.

3. DATABASE_URL이 가리키는 Postgres에 이미 db/schema.sql이 실행되어 있어야 합니다.

4. 최종 URL이 알려지면 GHL Marketplace 앱의 redirect URI를 <PUBLIC_URL>/oauth/ghl/callback으로 업데이트합니다.

Claude / ChatGPT에 연결

호스팅한 후:

• Claude.ai / Claude Desktop: 설정 → Connectors → Add custom connector → URL: https://<seu-dominio>/mcp. Claude가 자동으로 승인 흐름으로 안내합니다.

• ChatGPT: 원격 MCP Connectors를 지원하는 워크스페이스에서(플랜에 따라 다름 — Team, Enterprise 또는 "Developer mode"), https://<seu-dominio>/mcp를 가리키는 connector를 추가합니다.

ChatGPT에 대한 주의사항: ChatGPT의 OAuth를 사용하는 원격 MCP 커넥터 지원은 플랜/워크스페이스에 따라 다르며, 일부 인터페이스(예: Deep Research)는 허용하는 tool 형식을 제한합니다(때로는 "search"/"fetch" 형식의 tool만 허용). 이 서버는 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의 refresh token: 저장 시 암호화됨(AES-256-GCM).

• 이 서버가 Claude/ChatGPT에 발급하는 access/refresh token: SHA-256 해시로만 저장 — 비밀번호처럼 절대 평문으로 저장하지 않음.

• PKCE(S256)는 모든 MCP 측 흐름에서 필수이며, 로컬에서 검증됨(GHL에 위임하지 않음).

• 어떤 에이전시의 자격 증명도 다른 에이전시의 토큰으로 접근할 수 없습니다 — 모든 Postgres 접근은 companyId로 필터링되며, 그 값은 Bearer 토큰이 검증된 후에만 사용됩니다.