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

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 build

Configuration

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.jsonWindows: %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 start

Troubleshooting

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 information
contacts.write - Create and update tasks
conversations.readonly - Read conversations
conversations.write - Create/update conversations
conversations/message.readonly - Read messages
conversations/message.write - Send messages
calendars.readonly - Read calendars
calendars.write - Manage calendars
calendars/events.readonly - Read events
calendars/events.write - Create/update appointments

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.