GoHighLevel MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with the GoHighLevel API v2. This server enables AI assistants to interact with GoHighLevel's CRM, marketing automation, and business management tools.

Features

🚀 Complete API Coverage: Access to contacts, conversations, calendars, opportunities, payments, workflows, and more
🔐 Flexible Authentication: Supports both OAuth 2.0 and Private Integration tokens
⚡ Built-in Rate Limiting: Automatic rate limit management (100 requests/10s, 200k/day)
🛡️ Error Handling: Comprehensive error handling with detailed error messages
📦 Vercel Ready: Designed for deployment on Vercel with MCP support
🎯 Type-Safe: Full input validation and schema definitions for all tools

Installation

npm install ghl-mcp-server

Or install globally:

npm install -g ghl-mcp-server

Quick Start

1. Set up environment variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Edit .env with your GoHighLevel credentials:

# Private Integration Token (simplest method)
GHL_PRIVATE_TOKEN=your_private_integration_token_here

# Or use OAuth (for multi-account access)
GHL_CLIENT_ID=your_oauth_client_id
GHL_CLIENT_SECRET=your_oauth_client_secret

2. Configure your MCP client

Add to your Claude Desktop or other MCP client configuration:

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["ghl-mcp-server"],
      "env": {
        "GHL_PRIVATE_TOKEN": "your_token_here"
      }
    }
  }
}

3. Start using GoHighLevel tools

The server provides the following tools:

Contact Management

ghl_create_contact - Create a new contact
ghl_search_contacts - Search for contacts
ghl_get_contact - Get contact details
ghl_update_contact - Update contact information
ghl_delete_contact - Delete a contact
ghl_add_contact_tags - Add tags to a contact
ghl_remove_contact_tags - Remove tags from a contact

Conversations & Messaging

ghl_send_message - Send SMS, Email, or WhatsApp messages
ghl_get_conversations - Get conversation list
ghl_get_messages - Get messages in a conversation

Calendar & Appointments

ghl_create_calendar - Create a new calendar
ghl_create_appointment - Book an appointment
ghl_get_calendar_slots - Get available time slots
ghl_update_appointment - Update appointment details
ghl_cancel_appointment - Cancel an appointment

Sales & Opportunities

ghl_create_opportunity - Create a sales opportunity
ghl_search_opportunities - Search opportunities
ghl_update_opportunity - Update opportunity details
ghl_delete_opportunity - Delete an opportunity
ghl_get_pipelines - Get pipeline list

Payments

ghl_create_order - Create a payment order
ghl_get_transactions - Get transaction history
ghl_get_orders - Get order list

Automation

ghl_add_contact_to_workflow - Add contact to workflow
ghl_remove_contact_from_workflow - Remove from workflow
ghl_get_workflows - Get workflow list

Usage Examples

Create a Contact

{
  "tool": "ghl_create_contact",
  "arguments": {
    "locationId": "your_location_id",
    "contactData": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "tags": ["new-lead", "website"]
    }
  }
}

Send a Message

{
  "tool": "ghl_send_message",
  "arguments": {
    "type": "SMS",
    "contactId": "contact_id",
    "locationId": "location_id",
    "message": "Hello! Thanks for your interest."
  }
}

Create an Appointment

{
  "tool": "ghl_create_appointment",
  "arguments": {
    "appointmentData": {
      "calendarId": "calendar_id",
      "locationId": "location_id",
      "contactId": "contact_id",
      "startTime": "2025-07-23T15:00:00Z",
      "endTime": "2025-07-23T16:00:00Z",
      "title": "Consultation Call"
    }
  }
}

Authentication Methods

Method 1: Private Integration Token (Recommended for single account)

Go to Settings > Integrations > Private Integration in GoHighLevel
Create a new private integration
Copy the token and add to your .env file

Method 2: OAuth 2.0 (For marketplace apps)

Register your app in GoHighLevel Marketplace
Set up OAuth with the required scopes
Use the OAuth flow to get access tokens

Development

Running locally

# Install dependencies
npm install

# Run in development mode
npm run dev

Project Structure

ghl-mcp-server/
├── index.js              # Main server entry point
├── src/
│   ├── api-client.js     # GoHighLevel API client
│   ├── config.js         # Configuration constants
│   ├── rate-limiter.js   # Rate limiting logic
│   ├── error-handler.js  # Error handling utilities
│   └── tools/            # Tool definitions
│       ├── contact-tools.js
│       ├── conversation-tools.js
│       ├── calendar-tools.js
│       ├── opportunity-tools.js
│       ├── payment-tools.js
│       └── workflow-tools.js
└── package.json

Deployment on Vercel

Fork this repository
Connect to Vercel
Set environment variables in Vercel dashboard
Deploy

The server is designed to work with Vercel's MCP integration out of the box.

Error Handling

The server provides detailed error messages for common scenarios:

401 Unauthorized: Invalid or expired token
403 Forbidden: Insufficient permissions/scopes
404 Not Found: Resource not found
429 Rate Limited: Too many requests
422 Unprocessable Entity: Validation errors

Rate Limits

GoHighLevel enforces the following rate limits:

Burst: 100 requests per 10 seconds
Daily: 200,000 requests per day

The server automatically tracks and enforces these limits.

Contributing

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

License

MIT