Skip to main content
Glama
ghl-mcp-server

ghl-mcp-server

ghl-mcp-server

A GoHighLevel MCP server with every endpoint in HighLevel's public OpenAPI specs — 576 as of the committed catalog — generated straight from those specs. The official HighLevel MCP exposes ~36 tools; this one covers the whole public surface and stays current with one command. npm run generate prints the live total.

  • Generated, not hand-written. npm run generate turns specs/*.json into tool definitions. When HighLevel updates their docs, re-fetch and regenerate.

  • Context-friendly. Load only the modules you need (GHL_MODULES), and use three meta-tools (ghl_search_endpoints, ghl_describe_endpoint, ghl_call_endpoint) to reach everything else on demand. The default set is 52 tools, about 11k tokens of tool list; GHL_MODULES=all with writes and deletes on is ~213k tokens and will not fit in any model's context on its own.

  • Safe by default. Writes and deletes are off until you enable them. Disabled tools are hidden from the client entirely, not just blocked. Note what this does not mean: read tools in the default set can export every contact, conversation body, and call transcription in the sub-account. "Safe" here means no mutation, not small blast radius.

  • Public API only. Private Integration Token auth, no undocumented endpoints, no browser-session tokens.

Setup

npm install           # also builds, via the prepare script
cp .env.example .env  # then fill in GHL_API_KEY and GHL_LOCATION_ID
npm test              # optional: 42 tests, no credentials needed

specs/ and generated/ are committed, so a fresh clone is ready to run. npm run specs:fetch and npm run generate are for refreshing against HighLevel's docs — see Updating. Running them on a fresh clone replaces the specs you just checked out with whatever is on HighLevel's main today.

Get a Private Integration Token in GHL: sub-account → Settings → Private Integrations → Create. Enable the scopes for the endpoints you plan to use (e.g. contacts.readonly, contacts.write). Every tool description lists the scopes it needs.

Related MCP server: GoHighLevel MCP Server

Configuration

Variable

Default

Purpose

GHL_API_KEY

required

Private Integration Token

GHL_LOCATION_ID

—

Default sub-account; injected into any endpoint that takes locationId when the caller omits it

GHL_MODULES

contacts,conversations,opportunities,calendars,locations

Comma-separated modules to expose as dedicated tools, or all. Controls context size, not capability — see below

GHL_ALLOW_WRITES

false

Expose POST/PUT/PATCH tools

GHL_ALLOW_DELETES

false

Expose DELETE tools

GHL_META_TOOLS

true

Expose the three discovery/call meta-tools covering all endpoints

GHL_INCLUDE_DEPRECATED

false

List the 19 endpoints HighLevel marks deprecated as dedicated tools

GHL_BASE_URL

https://services.leadconnectorhq.com

API host override. Rejected unless it is https and stays on leadconnectorhq.com, because every request carries your token

MCP_AUTH_TOKEN

required for HTTP

Bearer token clients must send to the HTTP transport

PORT

3000

HTTP transport port

MCP_BIND_HOST

127.0.0.1

HTTP bind address. Anything but loopback exposes the server to the network

MCP_ALLOWED_HOSTS

—

Extra Host headers to accept, comma-separated. Needed behind a reverse proxy

GITHUB_TOKEN

—

Lifts GitHub's rate limit for npm run specs:fetch

GHL_MODULES is not a security boundary. With GHL_META_TOOLS=true (the default), ghl_call_endpoint can run any of the 576 endpoints in every module regardless of what is loaded. Only GHL_ALLOW_WRITES and GHL_ALLOW_DELETES constrain what can be done. Set GHL_META_TOOLS=false if you want module selection to be the limit.

Module names match the spec files: ad-manager, affiliate-manager, agent-studio, associations, blogs, brand-boards, businesses, calendars, campaigns, companies, contacts, conversation-ai, conversations, courses, custom-fields, custom-menus, email-isv, emails, forms, funnels, invoices, knowledge-base, links, locations, marketplace, medias, oauth, objects, opportunities, payments, phone-system, products, proposals, saas-api, snapshots, social-media-posting, store, surveys, users, voice-ai, workflows.

A few modules (companies, saas-api, snapshots, parts of locations and users) are agency-level and need an agency token; tool descriptions say Token: agency.

Use with Claude Code (stdio)

Add to .mcp.json in your project (or ~/.claude.json for global):

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["--env-file=/absolute/path/to/GHL-MCP/.env", "/absolute/path/to/GHL-MCP/dist/src/stdio.js"]
    }
  }
}

--env-file is built into Node, so no dotenv dependency. You can also put the variables in the "env" block of the config instead.

Use as a remote connector (Streamable HTTP)

MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm run start:http
# -> http://127.0.0.1:3000/mcp  (clients send: Authorization: Bearer <MCP_AUTH_TOKEN>)

The HTTP transport is stateless, refuses to start without MCP_AUTH_TOKEN, and binds loopback only. It serves POST /mcp (authenticated) and an unauthenticated GET /health that returns {"ok":true}.

To reach it from elsewhere, terminate TLS in front of it and set MCP_BIND_HOST plus MCP_ALLOWED_HOSTS=your.host:443. Without TLS the bearer token and every CRM record cross the wire in cleartext, and that token fronts a full-access Private Integration Token. Host headers outside the allowlist are rejected, which is what stops a hostile page from rebinding its own domain to your loopback address.

How the tools look

Each endpoint becomes {module}_{operationId}, for example contacts_upsert_contact, invoices_send_invoice, calendars_get_free_slots. Arguments are flat: path params, query params, and body fields all sit at the top level, and the server routes them to the right place. If a body isn't an object (e.g. an array), it's passed as a single body arg.

A field the spec marks as binary (file uploads) takes { "base64": "...", "filename": "rows.csv", "contentType": "text/csv" } and is sent as a real multipart file part.

Meta-tools:

  • ghl_search_endpoints({ query, module?, method?, limit? }) — keyword search over all 576

  • ghl_describe_endpoint({ name }) — full input schema, scopes, HTTP method/path

  • ghl_call_endpoint({ name, arguments }) — run any endpoint. Same write/delete gates, and arguments are validated against that endpoint's schema before anything is sent

Development

npm run dev          # run the stdio server from source (Node type-stripping)
npm run typecheck
npm test             # unit tests + in-memory end-to-end MCP tests

npm run dev runs the sources through Node's strip-only type stripping, which cannot erase enums, namespaces, or constructor parameter properties. erasableSyntaxOnly in tsconfig.json makes tsc reject that syntax, so the build fails instead of dev.

Layout:

scripts/fetch-specs.ts   download specs from GoHighLevel/highlevel-api-docs
src/generator/           OpenAPI -> endpoint definitions (pure, unit-tested)
generated/               committed catalog, one JSON per module
src/client.ts            fetch wrapper: auth, Version header, errors, 429 retry
src/tools.ts             tool registration, arg routing, gating, result formatting
src/meta-tools.ts        search / describe / call
src/server.ts            McpServer factory
src/stdio.ts, src/http.ts  transports

Updating when HighLevel changes the API

npm run specs:fetch && npm run generate && npm test

The generator refuses to write anything and exits non-zero if a spec produces a schema Zod can't express, a tool name collides or exceeds 64 characters, or a {placeholder} in a URL has no argument to fill it. generated/ is left untouched on failure, so a bad upstream change can neither ship silently nor half-replace the committed catalog.

That last check is not hypothetical: HighLevel's specs declare a path parameter on one method of a path and omit it on the others (GET /users/{userId} declares userId, PUT and DELETE do not). The generator reads placeholders from the URL template rather than trusting the parameter list, and the guard is there so a future gap fails the build.

Available Tools

55 tools
calendars_fetch_calendar_resourcesList Calendar ResourcesA
Read-onlyIdempotent

List Calendar Resources List calendar resources by resource type and location ID [GET /calendars/resources/{resourceType}] Token: location. Scopes: calendars/resources.readonly.

Inputs: skip (required), limit (required), locationId (required), resourceType (required).

calendars_find_event_notificationGet notificationC
Read-onlyIdempotent

Get notification Find Event notification by notificationId [GET /calendars/{calendarId}/notifications/{notificationId}] Scopes: calendars/events.readonly.

Inputs: calendarId (required), notificationId (required).

calendars_getallschedulesList user availability scheduleA
Read-onlyIdempotent

List user availability schedule Retrieve user availability schedules based on various filters including location, calendar, and user. Supports pagination. [GET /calendars/schedules/search] Scopes: calendars.readonly.

Inputs: userId (required), locationId (required), skip, limit, +1 more.

calendars_get_appointmentGet AppointmentB
Read-onlyIdempotent

Get Appointment Get appointment by ID [GET /calendars/events/appointments/{eventId}] Scopes: calendars/events.readonly.

Inputs: eventId (required).

calendars_get_appointment_notesGet NotesB
Read-onlyIdempotent

Get Notes Get Appointment Notes [GET /calendars/appointments/{appointmentId}/notes] Scopes: calendars/events.readonly.

Inputs: limit (required), offset (required), appointmentId (required).

calendars_get_blocked_slotsGet Blocked SlotsB
Read-onlyIdempotent

Get Blocked Slots [GET /calendars/blocked-slots] Scopes: calendars/events.readonly.

Inputs: endTime (required), startTime (required), locationId (required), userId, +2 more.

calendars_get_calendarGet CalendarA
Read-onlyIdempotent

Get Calendar Get calendar by ID [GET /calendars/{calendarId}] Scopes: calendars.readonly.

Inputs: calendarId (required).

calendars_get_calendar_eventsGet Calendar EventsC
Read-onlyIdempotent

Get Calendar Events [GET /calendars/events] Scopes: calendars/events.readonly.

Inputs: endTime (required), startTime (required), locationId (required), userId, +2 more.

calendars_get_calendar_resourceGet Calendar ResourceA
Read-onlyIdempotent

Get Calendar Resource Get calendar resource by ID [GET /calendars/resources/{resourceType}/{id}] Token: location. Scopes: calendars/resources.readonly.

Inputs: id (required), resourceType (required).

calendars_get_calendarsGet CalendarsA
Read-onlyIdempotent

Get Calendars Get all calendars in a location. [GET /calendars/] Scopes: calendars.readonly.

Inputs: locationId (required), groupId, showDrafted.

calendars_get_event_notificationGet notificationsC
Read-onlyIdempotent

Get notifications Get calendar notifications based on query [GET /calendars/{calendarId}/notifications] Scopes: calendars/events.readonly.

Inputs: calendarId (required), skip, limit, deleted, +1 more.

calendars_get_groupsGet GroupsA
Read-onlyIdempotent

Get Groups Get all calendar groups in a location. [GET /calendars/groups] Scopes: calendars/groups.readonly.

Inputs: locationId (required).

calendars_getschedulebyidGet user availability scheduleA
Read-onlyIdempotent

Get user availability schedule Retrieve a specific schedule by its unique identifier. Returns detailed information including rules, timezone, and associated calendars/users. [GET /calendars/schedules/{id}] Scopes: calendars.readonly.

Inputs: id (required).

calendars_get_slotsGet Free SlotsB
Read-onlyIdempotent

Get Free Slots Get free slots for a calendar between a date range. Optionally a consumer can also request free slots in a particular timezone and also for a particular user. [GET /calendars/{calendarId}/free-slots] Scopes: calendars.readonly.

Inputs: endDate (required), startDate (required), calendarId (required), userId, +2 more.

calendars_validate_groups_slugValidate group slugA
Read-only

Validate group slug Validate if group slug is available or not. [POST /calendars/groups/validate-slug] Scopes: calendars/groups.write.

Inputs: slug (required), locationId (required).

contacts_get_all_notesGet All NotesB
Read-onlyIdempotent

Get All Notes [GET /contacts/{contactId}/notes] Scopes: contacts.readonly.

Inputs: contactId (required).

contacts_get_all_tasksGet all TasksA
Read-onlyIdempotent

Get all Tasks [GET /contacts/{contactId}/tasks] Scopes: contacts.readonly.

Inputs: contactId (required).

contacts_get_appointments_for_contactGet Appointments for ContactA
Read-onlyIdempotent

Get Appointments for Contact [GET /contacts/{contactId}/appointments] Scopes: contacts.readonly.

Inputs: contactId (required).

contacts_get_contactGet ContactB
Read-onlyIdempotent

Get Contact [GET /contacts/{contactId}] Scopes: contacts.readonly.

Inputs: contactId (required).

contacts_get_contactsGet ContactsA
Read-onlyIdempotent

Get Contacts Note: This API endpoint is deprecated. Please use the Search Contacts endpoint instead. [GET /contacts/] Scopes: contacts.readonly. DEPRECATED.

Inputs: locationId (required), limit, query, startAfter, +1 more.

contacts_get_contacts_by_businessidGet Contacts By BusinessIdA
Read-onlyIdempotent

Get Contacts By BusinessId [GET /contacts/business/{businessId}] Scopes: contacts.readonly.

Inputs: businessId (required), locationId (required), skip, limit, +1 more.

contacts_get_duplicate_contactGet Duplicate ContactA
Read-onlyIdempotent

Get Duplicate Contact .If Allow Duplicate Contact is disabled under Settings, the global unique identifier will be used for searching the contact. If the setting is enabled, first priority for search is email and the second priority will be phone. [GET /contacts/search/duplicate] Scopes: contacts.readonly.

Inputs: locationId (required), email, number.

contacts_get_noteGet NoteB
Read-onlyIdempotent

Get Note [GET /contacts/{contactId}/notes/{id}] Scopes: contacts.readonly.

Inputs: id (required), contactId (required).

contacts_get_taskGet TaskB
Read-onlyIdempotent

Get Task [GET /contacts/{contactId}/tasks/{taskId}] Scopes: contacts.readonly.

Inputs: taskId (required), contactId (required).

contacts_search_contacts_advancedSearch ContactsB
Read-only

Search Contacts Search contacts based on combinations of advanced filters. Documentation Link - https://doc.clickup.com/8631005/d/h/87cpx-158396/6e629989abe7fad [POST /contacts/search] Scopes: contacts.readonly.

Inputs: body (required).

conversations_download_message_transcriptionDownload transcription by Message IDC
Read-onlyIdempotent

Download transcription by Message ID Download the recording transcription for a message by passing the message id [GET /conversations/locations/{locationId}/messages/{messageId}/transcription/download] Token: location. Scopes: conversations/message.readonly.

Inputs: messageId (required), locationId (required).

conversations_export_messages_by_locationExport messages by location IDA
Read-onlyIdempotent

Export messages by location ID Export messages for a specific location with cursor-based pagination support. Response includes messageType (string), source, and subType fields. The channel parameter is optional - if not provided, all non-email message types will be returned including activity messages (opportunity updates, appointments, etc.). [GET /conversations/messages/export] Scopes: conversations/message.readonly.

Inputs: locationId (required), limit, cursor, sortBy, +6 more.

conversations_get_all_custom_subtypesGet All Custom SubtypesC
Read-onlyIdempotent

Get All Custom Subtypes Get all custom subtypes for a location [GET /conversations/preferences/custom-subtypes]

Inputs: locationId (required).

conversations_get_contact_unsubscription_statusGet Contact Unsubscription StatusB
Read-onlyIdempotent

Get Contact Unsubscription Status Get all subscription statuses for a contact (all emails or specific email) [GET /conversations/preferences/unsubscriptions/status]

Inputs: contactId (required), locationId (required), email.

conversations_get_conversationGet ConversationB
Read-onlyIdempotent

Get Conversation Get the conversation details based on the conversation ID [GET /conversations/{conversationId}] Scopes: conversations.readonly.

Inputs: conversationId (required).

conversations_get_email_by_idGet email by IdC
Read-onlyIdempotent

Get email by Id [GET /conversations/messages/email/{id}]

Inputs: no named parameters.

conversations_get_messageGet message by message idA
Read-onlyIdempotent

Get message by message id . [GET /conversations/messages/{id}] Scopes: conversations/message.readonly.

Inputs: no named parameters.

conversations_get_message_recordingGet Recording by Message IDB
Read-onlyIdempotent

Get Recording by Message ID Get the recording for a message by passing the message id [GET /conversations/messages/{messageId}/locations/{locationId}/recording] Token: location. Scopes: conversations/message.readonly.

Inputs: messageId (required), locationId (required).

conversations_get_messagesGet messages by conversation idB
Read-onlyIdempotent

Get messages by conversation id . [GET /conversations/{conversationId}/messages] Scopes: conversations/message.readonly.

Inputs: conversationId (required), type, limit, lastMessageId.

conversations_get_message_transcriptionGet transcription by Message IDA
Read-onlyIdempotent

Get transcription by Message ID Get the recording transcription for a message by passing the message id [GET /conversations/locations/{locationId}/messages/{messageId}/transcription] Token: location. Scopes: conversations/message.readonly.

Inputs: messageId (required), locationId (required).

conversations_search_conversationSearch ConversationsB
Read-onlyIdempotent

Search Conversations Returns a list of all conversations matching the search criteria along with the sort and filter options selected. [GET /conversations/search] Scopes: conversations.readonly.

Inputs: locationId (required), id, sort, limit, +17 more.

ghl_call_endpointCall any GHL endpointA
Destructive

Execute any endpoint by tool name with a flat arguments object (path, query, and body fields all at top level; see ghl_describe_endpoint). Subject to the same write/delete gates as dedicated tools.

Inputs: name (required), arguments.

ghl_describe_endpointDescribe a GHL endpointA
Read-onlyIdempotent

Return the full input schema, required fields, auth scopes, and HTTP details for one endpoint by tool name.

Inputs: name (required).

ghl_search_endpointsSearch GHL endpointsA
Read-onlyIdempotent

Find GoHighLevel API endpoints by keyword across all 576 endpoints in 41 modules, including ones not loaded as dedicated tools. Returns tool names to pass to ghl_describe_endpoint / ghl_call_endpoint. Modules: ad-manager, affiliate-manager, agent-studio, associations, blogs, brand-boards, businesses, calendars, campaigns, companies, contacts, conversation-ai, conversations, courses, custom-fields, custom-menus, email-isv, emails, forms, funnels, invoices, knowledge-base, links, locations, marketplace, medias, oauth, objects, opportunities, payments, phone-system, products, proposals, saas-api, snapshots, social-media-posting, store, surveys, users, voice-ai, workflows.

Inputs: query (required), limit, method, module.

locations_get_all_or_email_sms_templatesGET all or email/sms templatesA
Read-onlyIdempotent

GET all or email/sms templates [GET /locations/{locationId}/templates] Scopes: locations/templates.readonly.

Inputs: originId (required), locationId (required), skip, type, +2 more.

locations_get_custom_fieldGet Custom FieldC
Read-onlyIdempotent

Get Custom Field [GET /locations/{locationId}/customFields/{id}]

Inputs: id (required), locationId (required).

locations_get_custom_fieldsGet Custom FieldsA
Read-onlyIdempotent

Get Custom Fields [GET /locations/{locationId}/customFields] Scopes: locations/customFields.readonly.

Inputs: locationId (required), model.

locations_get_custom_valueGet Custom ValueB
Read-onlyIdempotent

Get Custom Value [GET /locations/{locationId}/customValues/{id}]

Inputs: id (required), locationId (required).

locations_get_custom_valuesGet Custom ValuesB
Read-onlyIdempotent

Get Custom Values [GET /locations/{locationId}/customValues] Scopes: locations/customValues.readonly.

Inputs: locationId (required).

locations_get_locationGet Sub-Account (Formerly Location)A
Read-onlyIdempotent

Get Sub-Account (Formerly Location) Get details of a Sub-Account (Formerly Location) by passing the sub-account id [GET /locations/{locationId}] Token: location or agency. Scopes: locations.readonly.

Inputs: locationId (required).

locations_get_location_tagsGet TagsA
Read-onlyIdempotent

Get Tags Get Sub-Account (Formerly Location) Tags [GET /locations/{locationId}/tags] Scopes: locations/tags.readonly.

Inputs: locationId (required).

locations_get_recurring_task_by_idGet Recurring Task By IdC
Read-onlyIdempotent

Get Recurring Task By Id [GET /locations/{locationId}/recurring-tasks/{id}]

Inputs: id (required), locationId (required).

locations_get_tag_by_idGet tag by idA
Read-onlyIdempotent

Get tag by id [GET /locations/{locationId}/tags/{tagId}]

Inputs: tagId (required), locationId (required).

locations_get_timezonesFetch TimezonesA
Read-onlyIdempotent

Fetch Timezones Fetch the available timezones [GET /locations/{locationId}/timezones] Token: location. Scopes: locations.readonly.

Inputs: no named parameters.

locations_search_locationsSearchB
Read-onlyIdempotent

Search Sub-Account (Formerly Location) [GET /locations/search] Token: location or agency. Scopes: locations.readonly.

Inputs: skip, email, limit, order, +1 more.

opportunities_get_lost_reasonGet lost reasonC
Read-onlyIdempotent

Get lost reason [GET /opportunities/lost-reason] Scopes: opportunities.readonly.

Inputs: locationId (required), name, skip, limit, +3 more.

opportunities_get_opportunityGet OpportunityB
Read-onlyIdempotent

Get Opportunity [GET /opportunities/{id}] Scopes: opportunities.readonly.

Inputs: id (required).

opportunities_get_pipelinesGet PipelinesC
Read-onlyIdempotent

Get Pipelines [GET /opportunities/pipelines] Scopes: opportunities.readonly.

Inputs: locationId (required).

opportunities_search_opportunities_advancedSearch OpportunitiesC
Read-only

Search Opportunities based on combinations of advanced filters. Documentation Link - https://doc.clickup.com/8631005/d/h/87cpx-424216/7bf11bc9b94f80f [POST /opportunities/search] Scopes: opportunities.readonly.

Inputs: page (required), limit (required), query (required), locationId (required), +2 more.

opportunities_search_opportunitySearch OpportunityB
Read-onlyIdempotent

Search Opportunity [GET /opportunities/search] Scopes: opportunities.readonly.

Inputs: location_id (required), q, id, date, +16 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 55 tools

    Disambiguation2/5

    Several tools have unclear boundaries: opportunities_search_opportunity vs opportunities_search_opportunities_advanced, deprecated contacts_get_contacts vs contacts_search_contacts_advanced, and calendars_get_event_notification vs calendars_find_event_notification. The get/search/find verb variation across similar resources creates frequent ambiguity.

    Naming Consistency1/5

    Naming is highly inconsistent: module prefixes are mixed with camelCase (calendars_getallschedules, calendars_getschedulebyid), verbs vary between get/search/fetch/find, and singular/plural forms are inconsistent (opportunity vs opportunities, resource vs resources). There is no predictable overall pattern.

    Tool Count2/5

    At 55 tools, the server is far over the typical well-scoped range. While it covers multiple modules, the count feels bloated, especially since nearly all dedicated tools are read-only GETs and many could be consolidated.

    Completeness3/5

    The dedicated tool set has obvious gaps: there are no create/update/delete tools for contacts, conversations, tasks, notes, or appointments. However, the ghl_call_endpoint meta-tool exposes all 576 API endpoints, so agents can work around the missing operations, though this creates an awkward dependence on a generic escape hatch.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage GoHighLevel CRM data including contacts, conversations, opportunities, calendars, and forms through MCP tools and resources.
      53
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to GoHighLevel CRM via MCP, enabling full sub-account automation with 269+ tools for contacts, messaging, sales, marketing, and more.
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to directly interact with the entire GoHighLevel CRM via 563+ tools across 44 categories, allowing natural language control for contacts, messaging, opportunities, calendars, and more.
      16 npm
      1
      ISC