ghl-mcp-server-v2 — The Definitive GoHighLevel MCP Server

A from-the-ground-up MCP server covering the full public GoHighLevel API surface: 667 unique operations enumerated from the complete official OpenAPI spec corpus (84 spec files, legacy + v3 tiers). 651 tools registered; the other 16 are explicit, itemized exceptions (see api-coverage-checklist.md) — never silent omissions.

Built 2026-07-16 in a Cowork session (orchestrator + 8 parallel domain-audit sub-agents), following the mcp-builder skill's four-phase workflow. TypeScript, stdio transport, multi-tenant (locationId/companyId are call-time parameters — nothing tenant-specific is hardcoded).

Why this exists

The previous production connector (MCP_Servers/_to_delete/ghl-mcp-server-v1-retired) was a thin wrapper with silently incomplete coverage. Confirmed failures, all fixed here and locked in as regression checks (verified per-domain in docs/audits/):

Related MCP server: ghl-mcp

Architecture — how "no silently dropped field" is guaranteed

Tools are generated from the official OpenAPI specs, not hand-transcribed:

1. scripts/extract-operations.mjs parses every spec file, fully dereferences $refs, dedupes by METHOD /path (v3 spec variant preferred; legacy-only operations keep their legacy Version header), and emits src/generated/operations.json with request schemas verbatim.

2. src/registry.ts builds one MCP tool per operation: path/query/header params become top-level arguments; the request body schema is carried verbatim under a body argument. Missing path-param declarations in the spec are inferred from the URL template.

3. src/overrides/*.ts — eight domain-audit modules (one per sub-agent) carrying curated tool names, Version-header corrections, content-type overrides (multipart, form-urlencoded), agency-token warnings, and the 16 skip-with-reason exceptions.

Because the schema pipeline is mechanical, a field can only be missing if it is missing from GoHighLevel's own published spec — and the three known cases of that are documented in the audits (POST /contacts/search, object-record create/update, POST /forms/upload-custom-files), each exposed with a permissive body rather than dropped.

Setup

npm install
npm run build        # tsc + copies src/generated into build/
npm start            # stdio server
npm run inspect      # MCP Inspector smoke test

Client config (e.g. Claude Desktop / Cowork):

{
  "mcpServers": {
    "ghl-v2": {
      "command": "node",
      "args": ["<path>/ghl-mcp-server/build/index.js"],
      "env": { "GHL_API_KEY": "...", "GHL_ENABLE_WRITES": "false" }
    }
  }
}

Environment variables

Conventions

• Tool names: ghl_<resource>_<action> (snake_case, ≤64 chars), curated per domain (e.g. ghl_contact_update, ghl_opportunity_search, ghl_calendar_appointment_create, ghl_invoice_schedule_cancel).

• Annotations: readOnlyHint (GET), destructiveHint (DELETE), idempotentHint (GET/PUT/DELETE), openWorldHint always true.

• Multi-tenant: pass locationId / companyId / altId per call. ~44 platform ops require an agency-level (Company) token — their descriptions say so.

• Multipart uploads: pass file fields as { "filePath": "...", "filename?": "...", "mimeType?": "..." } inside body; the server builds the multipart request.

• Responses: structuredContent = { status, ok, data } plus pretty-printed text; errors return real HTTP status + body + actionable hints.

Deliverables map

• api-coverage-checklist.md — all 667 operations, per-row status, exceptions itemized. This is the proof of coverage.

• docs/audits/*.md — the 8 domain audit reports (regression verifications, renames, spec bugs found).

• docs/evaluation.xml — 10 verified evaluation Q&A pairs (mcp-builder Phase 4 format).

• docs/generated-names.json — "METHOD /path" → tool-name map.

Not done here (operator steps)

• Live testing. This was a docs-driven build; no live GHL call was made. Smoke-test read-only against a real location, then enable writes deliberately.

• Registering the server in a live MCP config (kept separate from the existing ghl-mcp-server registration — do not overwrite it without deciding to retire the old one).

• Re-run npm run extract && npm run build when GHL ships API changes; the checklist regenerates from the same pipeline.