ghl-mcp-server
This server is an MCP interface to GoHighLevel's entire public API, letting AI clients read (and optionally modify) CRM data through generated tools.
Search and manage contacts: advanced contact search, duplicate lookup, contact details, tasks, notes, and appointments.
Work with conversations: search conversations, fetch messages, email details, message recordings/transcriptions, and export messages by location.
Manage opportunities: search opportunities, advanced search, pipelines, lost reasons, and opportunity details.
Handle calendars: get calendars/groups, free slots, blocked slots, appointments, calendar events, resources, notifications, and availability schedules.
Access location data: search sub-accounts, get location details, tags, custom fields/values, templates, and timezones.
Use meta-tools to discover, describe, and call any of the 576 endpoints on demand, including modules not loaded as dedicated tools.
Safe by default: writes and deletes are hidden unless explicitly enabled, while read-only tools are available out of the box.
Run locally via stdio or as a remote authenticated HTTP MCP server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ghl-mcp-server List contacts created this week in my GoHighLevel account"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 generateturnsspecs/*.jsoninto 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=allwith 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 neededspecs/ 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 |
| required | Private Integration Token |
| — | Default sub-account; injected into any endpoint that takes |
|
| Comma-separated modules to expose as dedicated tools, or |
|
| Expose POST/PUT/PATCH tools |
|
| Expose DELETE tools |
|
| Expose the three discovery/call meta-tools covering all endpoints |
|
| List the 19 endpoints HighLevel marks deprecated as dedicated tools |
|
| API host override. Rejected unless it is https and stays on |
| required for HTTP | Bearer token clients must send to the HTTP transport |
|
| HTTP transport port |
|
| HTTP bind address. Anything but loopback exposes the server to the network |
| — | Extra |
| — | Lifts GitHub's rate limit for |
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 576ghl_describe_endpoint({ name })— full input schema, scopes, HTTP method/pathghl_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 testsnpm 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 transportsUpdating when HighLevel changes the API
npm run specs:fetch && npm run generate && npm testThe 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 toolscalendars_fetch_calendar_resourcesList Calendar ResourcesARead-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 notificationCRead-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 scheduleARead-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 AppointmentBRead-onlyIdempotent
Get Appointment Get appointment by ID [GET /calendars/events/appointments/{eventId}] Scopes: calendars/events.readonly.
Inputs: eventId (required).
calendars_get_appointment_notesGet NotesBRead-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 SlotsBRead-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 CalendarARead-onlyIdempotent
Get Calendar Get calendar by ID [GET /calendars/{calendarId}] Scopes: calendars.readonly.
Inputs: calendarId (required).
calendars_get_calendar_eventsGet Calendar EventsCRead-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 ResourceARead-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 CalendarsARead-onlyIdempotent
Get Calendars Get all calendars in a location. [GET /calendars/] Scopes: calendars.readonly.
Inputs: locationId (required), groupId, showDrafted.
calendars_get_event_notificationGet notificationsCRead-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 GroupsARead-onlyIdempotent
Get Groups Get all calendar groups in a location. [GET /calendars/groups] Scopes: calendars/groups.readonly.
Inputs: locationId (required).
calendars_getschedulebyidGet user availability scheduleARead-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 SlotsBRead-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 slugARead-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 NotesBRead-onlyIdempotent
Get All Notes [GET /contacts/{contactId}/notes] Scopes: contacts.readonly.
Inputs: contactId (required).
contacts_get_all_tasksGet all TasksARead-onlyIdempotent
Get all Tasks [GET /contacts/{contactId}/tasks] Scopes: contacts.readonly.
Inputs: contactId (required).
contacts_get_appointments_for_contactGet Appointments for ContactARead-onlyIdempotent
Get Appointments for Contact [GET /contacts/{contactId}/appointments] Scopes: contacts.readonly.
Inputs: contactId (required).
contacts_get_contactGet ContactBRead-onlyIdempotent
Get Contact [GET /contacts/{contactId}] Scopes: contacts.readonly.
Inputs: contactId (required).
contacts_get_contactsGet ContactsARead-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 BusinessIdARead-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 ContactARead-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 NoteBRead-onlyIdempotent
Get Note [GET /contacts/{contactId}/notes/{id}] Scopes: contacts.readonly.
Inputs: id (required), contactId (required).
contacts_get_taskGet TaskBRead-onlyIdempotent
Get Task [GET /contacts/{contactId}/tasks/{taskId}] Scopes: contacts.readonly.
Inputs: taskId (required), contactId (required).
contacts_search_contacts_advancedSearch ContactsBRead-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 IDCRead-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 IDARead-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 SubtypesCRead-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 StatusBRead-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 ConversationBRead-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 IdCRead-onlyIdempotent
Get email by Id [GET /conversations/messages/email/{id}]
Inputs: no named parameters.
conversations_get_messageGet message by message idARead-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 IDBRead-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 idBRead-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 IDARead-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 ConversationsBRead-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 endpointADestructive
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 endpointARead-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 endpointsARead-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 templatesARead-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 FieldCRead-onlyIdempotent
Get Custom Field [GET /locations/{locationId}/customFields/{id}]
Inputs: id (required), locationId (required).
locations_get_custom_fieldsGet Custom FieldsARead-onlyIdempotent
Get Custom Fields [GET /locations/{locationId}/customFields] Scopes: locations/customFields.readonly.
Inputs: locationId (required), model.
locations_get_custom_valueGet Custom ValueBRead-onlyIdempotent
Get Custom Value [GET /locations/{locationId}/customValues/{id}]
Inputs: id (required), locationId (required).
locations_get_custom_valuesGet Custom ValuesBRead-onlyIdempotent
Get Custom Values [GET /locations/{locationId}/customValues] Scopes: locations/customValues.readonly.
Inputs: locationId (required).
locations_get_locationGet Sub-Account (Formerly Location)ARead-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 TagsARead-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 IdCRead-onlyIdempotent
Get Recurring Task By Id [GET /locations/{locationId}/recurring-tasks/{id}]
Inputs: id (required), locationId (required).
locations_get_tag_by_idGet tag by idARead-onlyIdempotent
Get tag by id [GET /locations/{locationId}/tags/{tagId}]
Inputs: tagId (required), locationId (required).
locations_get_timezonesFetch TimezonesARead-onlyIdempotent
Fetch Timezones Fetch the available timezones [GET /locations/{locationId}/timezones] Token: location. Scopes: locations.readonly.
Inputs: no named parameters.
locations_search_locationsSearchBRead-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 reasonCRead-onlyIdempotent
Get lost reason [GET /opportunities/lost-reason] Scopes: opportunities.readonly.
Inputs: locationId (required), name, skip, limit, +3 more.
opportunities_get_opportunityGet OpportunityBRead-onlyIdempotent
Get Opportunity [GET /opportunities/{id}] Scopes: opportunities.readonly.
Inputs: id (required).
opportunities_get_pipelinesGet PipelinesCRead-onlyIdempotent
Get Pipelines [GET /opportunities/pipelines] Scopes: opportunities.readonly.
Inputs: locationId (required).
opportunities_search_opportunities_advancedSearch OpportunitiesCRead-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 OpportunityBRead-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
Scored across 55 tools
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 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.
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.
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
Related MCP Connectors
LeadConnector / GoHighLevel MCP Pack — wraps the GoHighLevel CRM for AI agents.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides access to over 460 tools within the GoHighLevel CRM, allowing AI assistants to manage contacts, opportunities, messaging, and business workflows through natural language.128ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage GoHighLevel CRM data including contacts, conversations, opportunities, calendars, and forms through MCP tools and resources.53AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to GoHighLevel CRM via MCP, enabling full sub-account automation with 269+ tools for contacts, messaging, sales, marketing, and more.ISC
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1ISC