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

1. Log into your GoHighLevel sub-account
2. Go to Settings > Integrations > Private Integrations
3. Click Create New Integration
4. Select the required scopes:
   • Contacts: Read, Write
   • Conversations: Read, Write
   • Conversation Messages: Read, Write
   • Calendars: Read, Write
   • Calendar Events: Read, Write
5. Copy the generated Private Integration Token
6. 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.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 start

Troubleshooting

Common Issues

1. "GHL_API_KEY and GHL_LOCATION_ID environment variables are required"

   • Ensure both environment variables are set correctly

2. "401 Unauthorized" errors

   • Verify your Private Integration Token is valid
   • Check that the token has the required scopes

3. "400 Bad Request" errors

   • Verify the request parameters match the API requirements
   • Check that IDs (contact, calendar, etc.) are valid

4. 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.