GoHighLevel MCP Server

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

Current API Coverage

• Official GHL endpoints parsed: 590
• Official endpoint coverage: 590 / 590
• Generated official endpoint tools: 238
• MCP tools in registry: 848 (816 raw API tools plus 32 curated agent workflow tools)
• Local-only endpoint references tracked for review: 253
• Daily GitHub Actions refresh opens a PR when the official GHL API docs change.

Coverage artifacts:

• docs/GHL-API-COVERAGE-REPORT.md
• docs/GHL-LOCAL-ENDPOINT-CLASSIFICATION.md
• docs/api-sources.lock.json
• docs/ghl-api-coverage.json
• docs/API-DASHBOARD.md
• docs/tool-inventory.json

Companion Tooling

The MCP server stays focused on MCP transports and GHL tool execution. Companion tooling lives beside it for setup, inspection, updates, and examples.

npm run tools:doctor       # Check build output, env, and API coverage health
npm run tools:list         # Browse the registered MCP tool inventory
npm run tools:report       # Regenerate the API dashboard and tool inventory JSON
npm run tools:explorer     # Print the local static tool explorer path
npm run tools:configure    # Print a Codex-compatible MCP config snippet
npm run tools:update-api   # Refresh official GHL API coverage and generated tools

Direct CLI usage:

npx ghl-mcp doctor
npx ghl-mcp list-tools --search ads
npx ghl-mcp configure codex
npx ghl-mcp test-tool search_contacts '{"locationId":"your_location_id","pageLimit":1}'

See docs/TOOLING.md for the full tooling map.

Contributors

See CONTRIBUTORS.md for contributor acknowledgements.

Agent Tool Profiles

By default, the server exposes the full tool surface: raw endpoint tools plus the curated CRM workflow layer. Agents that work better with fewer, higher-level actions or stricter stability boundaries can use:

GHL_TOOL_PROFILE=curated npm run start:stdio
GHL_TOOL_PROFILE=stable npm run start:stdio
GHL_TOOL_PROFILE=official npm run start:stdio

Profiles:

• full - default; exposes all 848 tools.
• curated - exposes only the 32 agent workspace tools, such as crm_prepare_lead_intake, crm_prepare_conversation_reply, crm_prepare_appointment_booking, and crm_location_health_check.
• raw - exposes only the original 816 endpoint-level tools.
• official - exposes explicit official OpenAPI and live-docs supplemental tools only.
• stable - exposes official, live-docs supplemental, curated, and legacy-compatible tools while hiding deprecated and private/unstable surfaces.

Every tool inventory entry includes a stability tier: official, live-docs-supplemental, legacy-compatible, private-or-unstable, or deprecated.

The curated tools return structured confirmation queues for writes. They stage the exact raw tool calls an agent should execute after the user confirms, instead of making outbound messages, billing, workflow enrollment, stage moves, or snapshot pushes feel like one ambiguous API call.

Recipes And Agent Starters

The examples/ directory turns the tool surface into practical MCP workflows:

• examples/recipes/ — structured JSON recipes for lead intake, appointment booking, pipeline follow-up, ads reporting, review requests, location health checks, and more.
• examples/agents/ — starter assistant prompts for CRM, appointment setting, pipeline management, ads reporting, and agency operations.
• docs/tool-explorer.html — static browser explorer for docs/tool-inventory.json.

Recipes use real MCP tool names and include confirmation points for actions like outbound messages, appointment creation, workflow enrollment, deletes, and snapshot pushes.

MCP Apps

mcp-apps/ contains companion MCP Apps for hosts that support interactive MCP resources. They run as a separate app server so the core MCP API server stays lean.

MCP Apps require Node 20+ because they use @modelcontextprotocol/ext-apps.

The apps are wired to the curated CRM workflow tools first, so buttons like "Prepare lead intake," "Prepare booking," and "Prepare snapshot rollout" produce confirmation-gated action plans for ChatGPT, Codex, or another MCP host.

npm run build
npm run apps:install
npm run apps:build
npm run apps:start:stdio

Included app tools:

• show_ghl_tool_explorer_app
• show_ghl_contact_workspace_app
• show_ghl_lead_intake_app
• show_ghl_conversation_inbox_app
• show_ghl_pipeline_board_app
• show_ghl_appointment_desk_app
• show_ghl_automation_launcher_app
• show_ghl_reputation_center_app
• show_ghl_ads_dashboard_app
• show_ghl_billing_commerce_app
• show_ghl_agency_admin_app

See mcp-apps/README.md for host config and HTTP mode.

For a normal browser preview:

npm run apps:start:http

Open http://localhost:3001/preview. The tool explorer links to every CRM workspace preview.

Transports

• npm run start:stdio — stdio MCP server for desktop MCP clients.
• npm run start:http — Streamable HTTP server at /mcp.
• npm run start:legacy — legacy SSE server at /sse.

The HTTP server also exposes:

• GET /health
• GET /capabilities
• GET /tools
• POST /execute
• POST /tools/call

Setup

npm install
cp .env.example .env

Set:

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

Build and run:

npm run build
npm run start:stdio

Verification

npm run scan:ghl-api
npm run validate:api-lock
npm test

docs/api-sources.lock.json records the official docs commit, expected endpoint counts, live-docs supplemental Email V2 pages, and acceptance gates verified on June 10, 2026. CI fails if generated coverage no longer matches this lock.

For HTTP:

npm run start:http

MCP Client Config

Example stdio config:

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/Go-High-Level-MCP-2026-Complete/dist/server.js"],
      "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"
      }
    }
  }
}

Scripts

npm run build              # Compile server files to dist/
npm run lint               # Fast TypeScript syntax/transpile check
npm test                   # Jest tests
npm run scan:ghl-api       # Refresh official GHL API coverage and generated tools
npm run ci:ghl-api-drift   # Fail if generated API artifacts are stale
npm run smoke:ghl-live     # Optional read-only live checks when GHL env vars are set
npm run tools:doctor       # Check local MCP setup
npm run tools:report       # Generate API dashboard and tool inventory
npm run tools:explorer     # Show the static tool explorer file path

Daily API Refresh

.github/workflows/ghl-api-drift.yml runs daily. It:

1. Pulls the latest official GoHighLevel/highlevel-api-docs snapshot.
2. Regenerates coverage docs and generated official endpoint tools.
3. Opens a PR if any generated artifacts changed.

PRs and pushes also run drift checks so stale generated files do not silently land.

Project Layout

src/
  clients/       GHL API clients
  tools/         MCP tool modules
  types/         shared TypeScript types
  main.ts        Streamable HTTP MCP server
  server.ts      stdio MCP server
  http-server.ts legacy SSE MCP server
scripts/         API scanner, generator, build, smoke test
docs/            generated API coverage reports
examples/        MCP recipes and starter agent templates
mcp-apps/        companion MCP Apps server and bundled UI
tests/           Jest tests

Notes

• src/tools/official-spec-tools.ts and src/tools/official-spec-endpoints.json are generated. Do not edit them by hand.
• Run npm run scan:ghl-api after GHL API docs change.
• The live smoke test is opt-in and only runs when GHL_API_KEY and GHL_LOCATION_ID are present.