Skip to main content
Glama
GoHighLevel MCP Server

GoHighLevel MCP Server

by geopopos

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

  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.

Available Tools

21 tools
complete_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

    B3.1/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive MCP server that connects AI assistants to GoHighLevel CRM, enabling management of contacts, conversations, calendars, pipelines, payments, and more through 60+ tools.
      64
      37 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP 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.
      50
      1
      MIT