GoHighLevel MCP Server

Model Context Protocol server for GoHighLevel. It exposes GHL API operations as MCP tools over stdio, Streamable HTTP, legacy SSE, and optional MCP Apps.

This fork adds two things on top of upstream:

1. OAuth 2.1 for remote deployment — a self-contained authorization server (dynamic client registration, PKCE, refresh tokens, password-gated consent) that secures the Streamable HTTP /mcp endpoint so it can be added directly to claude.ai as a custom connector. Enable it by setting MCP_OAUTH_PASSWORD.

2. Agency (Company) multi-sub-account mode — one agency OAuth credential, and you choose which sub-account to work in at runtime via ghl_list_subaccounts / ghl_select_subaccount / ghl_current_subaccount. Per-location tokens are minted on demand. Enable it with the GHL_AGENCY_* env vars.

Deploying it as a remote connector (Railway + Claude): see DEPLOY-RAILWAY.md.

Neither feature changes the default single-sub-account, local/stdio behavior — both are opt-in via environment variables.

New here? Start with QUICKSTART.md.

Using an AI/dev agent? Give it AGENT_SETUP.md and say: "Set this up for my MCP client using the curated profile. Ask me for credentials if needed. Do not run write tools."

5-Minute Quickstart

Requirements:

• Node 20+

• A GoHighLevel private integration token or OAuth access token

• A GoHighLevel Location ID

npm install
cp .env.example .env
npm run build
npm run doctor
npm run configure:codex

Add your credentials to .env:

GHL_API_KEY=your_private_integration_api_key
GHL_LOCATION_ID=your_location_id
GHL_BASE_URL=https://services.leadconnectorhq.com
GHL_API_VERSION=2023-02-21

GHL_API_VERSION=2023-02-21 is the current HighLevel API Version header used by official docs. It is not the project year, and it should not be changed to 2026 unless HighLevel publishes a new required API version.

Then verify live auth:

npm run auth-check

Related MCP server: GoHighLevel MCP Server

Setup Commands

npm run setup                 # Create .env if needed, build, and print next steps
npm run first-run             # One-command beginner setup/readiness flow
npm run connect               # Setup plus client config generation
npm run ready                 # Fast readiness check
npm run demo                  # Print MCP Apps demo preview instructions
npm run explain-error -- "Location is not active"
npm run doctor                # Human-readable setup check
npm run doctor -- --json      # Agent-readable setup check
npm run agent:check           # Safe validation for AI/dev agents
npm run auth-check            # Read-only GHL token/location check

Missing credentials are reported as needsHumanAction, not as a broken install. This lets agents build and configure the repo without inventing secrets.

MCP Client Config

Beginner configs use GHL_TOOL_PROFILE=curated so agents see the high-level workflow tools first.

npm run configure:codex
npm run configure:claude
npm run configure:cursor
npm run configure:windsurf

Advanced examples:

node scripts/ghl-mcp.mjs configure codex --profile stable
node scripts/ghl-mcp.mjs configure codex --profile full
node scripts/ghl-mcp.mjs configure codex --profile curated --json

Tool Profiles

• curated - recommended for agents; high-level CRM workflows with confirmation queues.

• stable - production-friendly; official, supplemental, curated, and legacy-compatible tools.

• full - everything.

• official - official OpenAPI and live-docs supplemental tools.

• raw - endpoint-level tools only.

Run

npm run start:stdio       # Desktop MCP clients
npm run start:http        # Streamable HTTP at /mcp
npm run start:legacy      # Legacy SSE at /sse

HTTP also exposes:

• GET /health

• GET /capabilities

• GET /tools

• POST /execute

• POST /tools/call

MCP Apps

npm run apps:setup
npm run apps:preview

Open http://localhost:3001/preview. Without GHL credentials, the apps use preview/demo states and tell you exactly which env vars are missing.

Tool Discovery

npm run tools:list
npm run tools:list -- --search contacts
npm run tools:list -- --category contacts
npm run tools:list -- --stability official
npm run tools:list -- --access write
npm run tools:list -- --destructive
npm run tools:explorer

The static explorer is docs/tool-explorer.html.

High-Level Agent Tools

Start agents with the curated profile and prefer these high-level tools before raw endpoints:

• crm_location_overview

• crm_daily_briefing

• crm_search_everything

• crm_next_best_actions

• crm_get_next_page

• crm_prepare_contact_followup

• crm_prepare_lead_reactivation

• crm_prepare_missed_call_response

• crm_prepare_pipeline_cleanup

• crm_prepare_review_request_batch

• crm_prepare_invoice_followup

Docs

• Update Log

• Setup

• Usage

• Clients

• Tool Profiles

• Recipes

• Safety

• Troubleshooting

• Deployment

• Development

• API Coverage

• Companion Tooling

Update History

API Coverage

• Official GHL endpoints parsed: 590

• Official endpoint coverage: 590 / 590

• Generated official endpoint tools: 238

• MCP tools in registry: 848

• Local-only endpoint references tracked for review: 253

Generated coverage artifacts live in docs/. Run npm run scan:ghl-api only when intentionally refreshing API coverage.

Safety

• .env is ignored and must never be committed.

• test-tool refuses write/destructive tools unless --confirm is supplied.

• Curated workflow tools stage confirmation queues for writes.

• Use curated for beginners and stable for production.

Credits

This project is a fork of and builds on BusyBee3333/Go-High-Level-MCP-2026-Complete, which provides the underlying GoHighLevel MCP server and tool coverage. That project is licensed under ISC; see LICENSE for the original copyright notice.

This fork adds the OAuth 2.1 remote-connector layer and the agency (Company) multi-sub-account mode described above.