GoHighLevel (GHL) 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.

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=v3
GHL_API_GENERATION=v3
# GHL_USER_TYPE=Location # or Company; optional access preflight

GHL_API_VERSION=v3 is the current named HighLevel API Version header, not a date. Routing is per endpoint: ad-publishing remains mostly on 2021-07-28; Conversations use v3 in current mode and 2021-04-15 in legacy v2 mode. Set GHL_API_GENERATION=v2 for the legacy surface; the starter GHL_API_VERSION=v3 value is then replaced by the 2023-02-21 fallback. See docs/V3-MIGRATION.md.

Then verify live auth:

npm run auth-check

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

Date	Update #	Included
2026-06-11	2	Simplicity and power layer: easy setup commands, safe config writing, grouped live smoke checks, and high-level curated CRM agent tools. See UPDATE_LOG.md for the full permanent update description.
2026-06-11	1	Onboarding and agent setup overhaul. See UPDATE_LOG.md for the full permanent update description.

API Coverage

• Official endpoint references parsed: 1221 (v3 repo: 627, v2 repo: 590, current live-docs v3: 4)
• Current/default v3 coverage: 661 / 661 (100%)
• Legacy v2 compatibility coverage: 590 / 590 (100%)
• Dual-generation union coverage: 681 / 681 (100%)
• Generated official endpoint tools: 543
• MCP tools in the full registry: 926
• Local-only endpoint references: current v3 265; dual-generation union 245

The scanner reads both the v2 (apps/*.json) and v3 (apps/v3/*-v3.json) OpenAPI fragments. v3 endpoints are the source of truth; superseded v2 entries are retained for GHL_API_GENERATION=v2 legacy mode.

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.