GoHighLevel MCP Server

Сервер Model Context Protocol, который даёт LLM-агенту оперативный контроль над CRM GoHighLevel — 114 инструментов в 24 модулях, охватывающих контакты, воронки, календари, обмен сообщениями, выставление счетов и платежи через GoHighLevel API v2.

Проблема

GoHighLevel — основная учётная система небольшого агентства: каждый клиент, каждая бronь, каждый счёт. Работа, которая на самом деле съедает весь день, — это не отдельное действие в CRM, а сшивание этих действий между бой: съёмка подтверждена — зnачit, нужто создать сделки, перевес in нуж constantly этап воรонкi, забronировать слайт в календаре на нужного контаrit, с setUp счёт and оставить заметку. Каждый шаг — that's trитцать секунбод кликов, и такая послedовательность повтоเรียтся несолько раз в неделю.

Именно такую цепочку allowed to speak consumed agent, if he gets CRM. This server is it, this access: it represents GoHighLevel tools and annotated tools, enabling the agent to execute the chain from one command sentence, while destructive and external actions remain visible for approval.

Related MCP server: GoHighLevel MCP Server

Architecture

24 tool modules are registered in one McpServer over stdio. All requests go through the unified ghlRequest(), which is responsible for authentication, the required Version header, query-string assembly, and simplification of errors. Modules can be toggled during startup via GHL_DISABLED_MODULES — it matters much more than it seems, because 114 tool definitions are a significant part of the agent's context window before he has read at least one word from the user's request. The configuration that works only with booking can register six modules and skip the rest.

  MCP host (Claude Desktop / Claude Code)
          | stdio (JSON-RPC)
  +-------v--------------------------------------------+
  |  index.ts   MODULES registry, GHL_DISABLED_MODULES  |
  +-------+--------------------------------------------+
          |
  +-------v-----+ +---------------+ +-----------+ ......  24 modules
  |  contacts   | | opportunities | | invoices  |
  +-------+-----+ +-------+-------+ +-----+-----+
          |               |               |
          |               |         +-----v--------------+
          |               |         | billing-helpers.ts |
          |               |         |  businessDetails   |
          |               |         |  contactDetails    |
          |               |         |  sender resolution |
          |               |         +-----+--------------+
          +-------+-------+---------------+
                  |
        +---------v----------------------------+
        |  client.ts  ghlRequest()             |
        |   Bearer token + Version header      |
        |   status-specific error hints        |
        +---------+----------------------------+
                  |
          services.leadconnectorhq.com

Every write tool carries MCP annotations — 17 marked destructiveHint, and ghl_send_message / ghl_send_invoice indicated as outgoing because they contact real customers. The host shows them before approving the call, and this is the difference between an agent who creates an invoice request and an agent who sends it to the client by accident.

Really complicated part

Creating an invoice. Endpoint accepts businessDetails and contactDetails blocks, and the documentation not communicates that for both blocks: send contactId and a couple of positions, as the documentation suggests, and you get a validation error that does not point to any file. Both blocks are required in full, and businessDetails.phoneNo and contactDetails.phoneNo are mandatory: contact with E -mail BUT phone number without phone cannot be issued at all.

Moreover, values must match what the UI creates, otherwise invoices created through API differ from those made manually — another logo, no details, wrong numbering. By default, these values are not in the location profile where they could be expected — they are located behind GET /invoices/settings, that is, there, from where the UI copies them into the form.

src/tools/billing-helpers.ts detects both blocks, and tools only need contactId. The business details are resolved at four levels — the per-call argument, GHL_BUSINESS_* environment, saved invoice settings, location profile — and each level fills only what the previous one left empty. Contact details are requested and assembled, with the name embedded according to the following chain: full name, name and surname, company name, Email, then phone, - because GoHighLevel rejects empty name, and in actual CRM records it is often absent. Both paths throw a message that indicates the missing field and how to fill it, instead of returning GHL's opaque error 422. Each lookup is memoized per location, so ten invoices cost one request for settings, not ten.

what I would have done otherwise

1. No tests. 4,000 lines and none. Scope chain in billing-helpers is pure logic on fixed data: it's the easiest thing to test in the repository, and the most expensive to make a mistake, because the failure mode is a malformed invoice sent to a client.

2. No retake on 429. ghlRequest reports "frequency limit is hit; rotate with short delay", and then does not retake. Exponentially delayed backup should live in the client, not in the agent's judgment.

3. Cashes are module-level changing maps without invalidation. For the stdio server, which the host can restart without problems, this is normal; but wrong-ass, how to start this as a long-lived process, where a change in business profile is never executed.

4. Responses have Record<string, unknown> everywhere. GoHighLevel publishes the OpenAPI specification; the generation of types from it would turn a whole class of runtime surprises into compile-time errors.

5. 114 tools in one server is too much. Module toggles are a workaround, not a solution. The correct option is a small set of tools plus detection mechanism so that the agent pays only for what it uses.

Setting

Requires Node 20+ and GoHighLevel account.

1. Create a private integration token

Settings → Private integrations → Create a new integration. Include the appropriate right scope with tools you intend to use; at minimum:

contacts.readonly, contacts.write, opportunities.readonly, opportunities.write, calendars.readonly, calendars / messages.write, invoices:readonly, invoices:write, products.readonly, products.write, locations/customFields.readonly, workflows.readonly

Copy the token — it starts with pit-.

2. Find Location ID

Settings → Business Profile, or take it from the URL on the dashboard: .../location/<LOCATION_ID>/...

3. Build

git clone <this-repo>
cd ghl-mcp
npm install
npm run build

4. Register from the MCP host

{
  "mcpServers": {
    "gohighlevel": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

Restart the host. All supported environments — see .env.example, including invoice business block and module toggles.

To try server without host:

GHL_API_KEY=pit-... GHL_LOCATION_ID=... npm run inspect

Note on "automation"