GoHighLevel 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., "@GoHighLevel MCP Server Search for all unread conversations"
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.
GoHighLevel MCP Server
A Model Context Protocol (MCP) server that provides tools for managing GoHighLevel (GHL) conversations, tasks, and calendar appointments through AI assistants like Claude.
Features
Conversations
search_conversations - Search and filter conversations with various criteria
get_conversation - Get details of a specific conversation
create_conversation - Create a new conversation with a contact
update_conversation - Update conversation (star, assign, mark as read)
delete_conversation - Delete a conversation
get_messages - Get messages in a conversation
send_message - Send SMS, Email, WhatsApp, or other message types
Tasks
get_tasks - Get all tasks for a contact
get_task - Get a specific task
create_task - Create a new task
update_task - Update an existing task
delete_task - Delete a task
complete_task - Mark a task as completed/incomplete
Calendar & Appointments
get_calendars - Get all calendars in the location
get_calendar - Get details of a specific calendar
get_free_slots - Get available time slots
get_calendar_events - Get events within a date range
get_appointment - Get appointment details
create_appointment - Create a new appointment
update_appointment - Update an appointment
delete_appointment - Delete an appointment
Related MCP server: ghl-mcp
Prerequisites
Node.js 18 or higher
A GoHighLevel account with API access
A Private Integration Token (PIT) from GoHighLevel
Getting Your GHL Credentials
Log into your GoHighLevel sub-account
Go to Settings > Integrations > Private Integrations
Click Create New Integration
Select the required scopes:
Contacts: Read, Write
Conversations: Read, Write
Conversation Messages: Read, Write
Calendars: Read, Write
Calendar Events: Read, Write
Copy the generated Private Integration Token
Note your Location ID (found in Settings > Business Profile or in the URL)
Installation
# Clone or download this repository
cd ghl-mcp-server
# Install dependencies
npm install
# Build the project
npm run buildConfiguration
Environment Variables
Set the following environment variables:
export GHL_API_KEY="pit-your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"Claude Desktop Configuration
Add the server to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"ghl": {
"command": "node",
"args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
"env": {
"GHL_API_KEY": "pit-your-private-integration-token",
"GHL_LOCATION_ID": "your-location-id"
}
}
}
}Cursor IDE Configuration
Add to your Cursor MCP settings:
{
"mcpServers": {
"ghl": {
"command": "node",
"args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
"env": {
"GHL_API_KEY": "pit-your-private-integration-token",
"GHL_LOCATION_ID": "your-location-id"
}
}
}
}Usage Examples
Once configured, you can use natural language to interact with your GHL account:
Conversations
"Search for all unread conversations"
"Get messages from conversation ID xyz123"
"Send an SMS to contact abc456 saying 'Thank you for your inquiry!'"
"Send an email to contact abc456 with subject 'Follow Up' and body 'Hi, just following up...'"
Tasks
"Show me all tasks for contact xyz123"
"Create a task for contact abc456: Call back tomorrow at 2pm"
"Mark task xyz as completed"
"Update task abc to change the due date to next Monday"
Calendar
"List all calendars"
"Show me appointments for the next 7 days"
"Get free slots for calendar xyz between Jan 15 and Jan 20"
"Create an appointment for contact abc456 on January 15th at 10am"
"Cancel appointment xyz123"
API Reference
Conversation Tools
search_conversations
Search conversations with filters like contactId, assignedTo, query text, status, and message direction.
send_message
Send messages with support for:
SMS: Simple text messages
Email: With subject, HTML body, CC/BCC, attachments
WhatsApp: WhatsApp messages
IG/FB: Instagram and Facebook messages
Live_Chat: Live chat messages
Task Tools
create_task
Create tasks with:
Title (required)
Description/body
Due date (ISO 8601 format)
Assignment to specific user
Completion status
Calendar Tools
create_appointment
Create appointments with:
Calendar ID (required)
Contact ID (required)
Start/end time (ISO 8601 format)
Title and description
Meeting location (Zoom, Google Meet, custom, etc.)
Appointment status
Notifications/automations toggle
Development
# Run in development mode
npm run dev
# Build only
npm run build
# Start production server
npm startTroubleshooting
Common Issues
"GHL_API_KEY and GHL_LOCATION_ID environment variables are required"
Ensure both environment variables are set correctly
"401 Unauthorized" errors
Verify your Private Integration Token is valid
Check that the token has the required scopes
"400 Bad Request" errors
Verify the request parameters match the API requirements
Check that IDs (contact, calendar, etc.) are valid
Server not appearing in Claude Desktop
Verify the path to the server is correct
Check the Claude Desktop logs for errors
Restart Claude Desktop after configuration changes
Required Scopes
For full functionality, your Private Integration Token needs these scopes:
contacts.readonly- Read contact informationcontacts.write- Create and update tasksconversations.readonly- Read conversationsconversations.write- Create/update conversationsconversations/message.readonly- Read messagesconversations/message.write- Send messagescalendars.readonly- Read calendarscalendars.write- Manage calendarscalendars/events.readonly- Read eventscalendars/events.write- Create/update appointments
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Available Tools
21 toolscomplete_taskB
Mark a task as completed or incomplete
Inputs: taskId (required), completed (required), contactId (required).
create_appointmentB
Create a new appointment/calendar event
Inputs: contactId (required), startTime (required), calendarId (required), title, +7 more.
create_conversationB
Create a new conversation with a contact
Inputs: contactId (required).
create_taskB
Create a new task for a contact
Inputs: title (required), dueDate (required), contactId (required), body, +2 more.
delete_appointmentC
Delete/cancel an appointment
Inputs: eventId (required).
delete_conversationC
Delete a conversation
Inputs: conversationId (required).
delete_taskC
Delete a task
Inputs: taskId (required), contactId (required).
get_appointmentB
Get details of a specific appointment
Inputs: eventId (required).
get_calendarB
Get details of a specific calendar
Inputs: calendarId (required).
get_calendar_eventsA
Get calendar events/appointments within a date range
Inputs: endTime (required), startTime (required), userId, groupId, +1 more.
get_calendarsB
Get all calendars in the location
Inputs: no named parameters.
get_conversationA
Get details of a specific conversation by ID
Inputs: conversationId (required).
get_free_slotsC
Get available time slots for a calendar
Inputs: endDate (required), startDate (required), calendarId (required), userId, +1 more.
get_messagesA
Get messages in a conversation
Inputs: conversationId (required), limit, lastMessageId.
get_taskA
Get a specific task by ID
Inputs: taskId (required), contactId (required).
get_tasksB
Get all tasks for a specific contact
Inputs: contactId (required).
search_conversationsA
Search and filter conversations in GoHighLevel. Returns a list of conversations matching the search criteria.
Inputs: limit, query, status, contactId, +2 more.
send_messageB
Send a message to a contact (SMS, Email, WhatsApp, etc.)
Inputs: type (required), contactId (required), html, emailTo, +5 more.
update_appointmentC
Update an existing appointment
Inputs: eventId (required), title, address, endTime, +5 more.
update_conversationA
Update a conversation (star/unstar, assign to user, mark as read)
Inputs: conversationId (required), starred, assignedTo, unreadCount.
update_taskC
Update an existing task
Inputs: taskId (required), contactId (required), body, title, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Tools are clearly grouped by resource (conversations, tasks, calendars), and each has a distinct action. The only minor overlap is between get_calendar_events and get_appointment, but descriptions clarify that one lists events by date range while the other fetches a specific appointment.
Most tools follow a consistent verb_noun pattern in snake_case (e.g., create_conversation, update_task, delete_appointment). Minor deviations include pluralization differences (get_messages vs get_conversation) and the special case 'complete_task', but the overall convention is predictable.
21 tools is on the heavier side, falling into the 'feels heavy' range (16-25). However, the count is justified by covering CRUD for three distinct domains (conversations, tasks, appointments), so it is not excessive.
The server provides full CRUD for conversations, tasks, and appointments, plus message retrieval and sending. Minor gaps exist such as no update/delete for messages and no management of calendars themselves, but these are not critical to the core workflows.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted CallRail MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Related MCP Servers
- AlicenseBqualityDmaintenanceA comprehensive MCP server that connects AI assistants to GoHighLevel CRM, enabling management of contacts, conversations, calendars, pipelines, payments, and more through 60+ tools.6437 npm1MIT
- AlicenseBqualityDmaintenanceMCP server for GoHighLevel API v2 that provides 50+ tools for CRM, billing, marketing, and operations workflows, enabling natural language interaction with contacts, opportunities, conversations, and more.501MIT
- AlicenseCqualityBmaintenanceA Model Context Protocol (MCP) server for GoHighLevel API v2 — giving any AI agent full access to your GHL location.100440 npm6MIT
- AlicenseAqualityDmaintenanceMCP server that lets you talk to your GoHighLevel sub-account in plain English, offering six tools to search contacts, list calendars, check free slots, and book appointments with dry-run safety and explicit error messages.6MIT