@aiwerk/mcp-server-ghl

MCP server for the GoHighLevel (GHL) API, the CRM and marketing automation platform used by agencies to run their clients' sales pipelines, calendars, conversations and campaigns.

569 tools across 41 domains, generated from GHL's official OpenAPI 3.0.0 specification.

Contacts       Opportunities   Conversations   Calendars      Invoices
Payments       Workflows       Campaigns       Forms          Surveys
Funnels        Blogs           Courses         Products       Store
Social Media   Ad Manager      SaaS API        Snapshots      Custom Fields

Why generated

Every endpoint, HTTP verb, parameter and field name comes from the official specification rather than from prose documentation, so the tool surface can't drift from what GHL actually accepts. What the specification can't tell you, which endpoints need an agency-level token instead of a location one, which API version an endpoint expects, which fields the docs forgot to mark required, is layered on top by hand. See GHL specifics worth knowing.

Install

npm install -g @aiwerk/mcp-server-ghl

Requires Node.js 18 or newer.

Authentication

Create a Private Integration Token (PIT) in the target location under Settings > Private Integrations. A PIT is scoped to one location, it is not an agency-wide credential, and most tools need to know which location they're acting on.

export GHL_PIT_TOKEN="your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"

Usage

Claude Code

claude mcp add ghl \
  --env GHL_PIT_TOKEN=your-token \
  --env GHL_LOCATION_ID=your-location-id \
  -- npx -y @aiwerk/mcp-server-ghl

Claude Desktop

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-ghl"],
      "env": {
        "GHL_PIT_TOKEN": "your-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}

AIWerk hosted service

Install it from the catalogue at aiwerkmcp.com and add your token in the interface. No local setup required.

Safety features

Dry run

export GHL_DRY_RUN=1

Every write (POST/PUT/PATCH/DELETE) is stopped before it reaches GHL and returns a description of the request that would have been sent. Reads still work normally.

Agency-only endpoints get a clear error, not a bare 401

39 endpoints (snapshots, the SaaS API, agency OAuth token exchange, creating custom objects) require an agency-level token. A location PIT gets a plain 401 from GHL for these with no explanation in the body, the server knows which endpoints these are and returns a message saying so, instead of making it look like a bad or expired token.

locationId is filled in automatically

A PIT is already scoped to one location, so 430 of the 569 tools accept locationId (or altId/altType) as an optional parameter, if the calling agent doesn't supply one, the server falls back to GHL_LOCATION_ID. This also means a tool call can't accidentally target the wrong location by a copy-pasted id from a different account, since the default always matches the token's own scope.

Configuration

| Variable | Default | Purpose | |---|---|---| | GHL_PIT_TOKEN | required | Private Integration Token | | GHL_LOCATION_ID | required | Location the PIT is scoped to; default for locationId/altId params | | GHL_API_BASE_URL | https://services.leadconnectorhq.com | Override the host | | GHL_API_TIMEOUT_MS | 30000 | Per request timeout | | GHL_DRY_RUN | off | 1 blocks all writes | | GHL_MAX_RATE_LIMIT_WAIT_MS | 10000 | Longest wait before failing on a rate limit | | GHL_ENABLED_TAGS | all | Comma separated domain filter, for example contacts,invoices |

Narrowing the tool set

All 569 tools are registered by default. A client that prefers a smaller surface can restrict the server to specific domains (domain names are hyphenated, e.g. social-media-posting, ad-manager):

export GHL_ENABLED_TAGS="contacts,opportunities,conversations,calendars"

Unknown domain names are reported on startup rather than silently ignored.

A few GHL specifics worth knowing

• The API version differs per endpoint, not globally. GHL sends a Version request header (2021-07-28 or 2021-04-15) that the server sets per call based on what each endpoint actually expects, a wrong version returns a different response shape silently, not an error, so there's no single default to fall back on. 29 endpoints send no version header at all; the server matches that too.
• A location PIT cannot call agency-only endpoints, ever, no scope fixes it. snapshots/*, saas-api/*, oauth/locationToken, oauth/installedLocations, and creating custom objects (POST /objects) need an agency-level credential.
• 11 endpoints in the official spec omit a path parameter's declaration (e.g. a noteId on some calendar/conversation routes, a postId on blogs, a type on contacts). The generator fills these in as required string fields since the parameter is clearly used in the path template, this is an upstream spec gap, not something introduced here.
• Rate limits have not yet been measured against a live account. The client retries on 429 using whatever Retry-After GHL sends, but does not pre-emptively throttle with an invented number, an assumed limit that's wrong would either under-use the account or start failing calls that would have succeeded.

Testing

npm test          # unit tests, mocked fetch
npm run smoke      # read only, against a live account

Development

The tool layer is generated and must not be edited by hand:

npm run gen-naming   # specification  ->  tool names
npm run gen-tools    # specification  ->  zod schemas and call sites
npm run build

Licence

MIT, see LICENSE.

Built by AIWerk. Not affiliated with GoHighLevel / HighLevel Inc.