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: Google Tasks MCP Server

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.