io.github.northrosetech/ghl-mcp-server

GHL MCP Server

GoHighLevel MCP Server for Claude, N8N, and Custom AI Agents Built by Saurabh K Shah (https://saurabhshah.com)

A comprehensive Model Context Protocol (MCP) server that connects AI assistants directly to your GoHighLevel CRM. Supports 60+ tools across contacts, conversations, calendars, pipelines, payments, invoices, workflows, custom fields, social media, and more.

Features

• Contacts: Search, create, update, delete, upsert, tags, notes, tasks, workflow management
• Conversations & Messaging: SMS, Email, WhatsApp, search threads, send messages, schedule sends
• Calendars & Appointments: List calendars, get free slots, create/update/delete events
• Opportunities & Pipelines: Full deal management, stage transitions, pipeline listing
• Payments & Invoices: Orders, transactions, subscriptions, create/send/void invoices
• Workflows: List all workflows, add/remove contacts from workflows
• Custom Fields: List, create custom fields for contacts
• Locations: Sub-account details, tags management
• Users: Search team members
• Forms & Surveys: List forms/surveys, get submissions
• Campaigns: List all campaigns
• Social Media: List/create posts, view connected accounts
• Funnels & Blogs: List funnels, blogs
• Products: List products and prices

Quick Start

1. Get Your GHL Credentials

1. Log into GoHighLevel → Settings → Private Integrations
2. Click Create New Integration
3. Name it (e.g., "Claude MCP Server")
4. Select all scopes you need (contacts, conversations, calendars, payments, etc.)
5. Copy the Private Integration Token
6. Note your Location ID (visible in the URL when viewing any sub-account)

2. Install & Configure

git clone https://github.com/northrosetech/ghl-mcp-server.git
cd ghl-mcp-server
npm install
cp .env.example .env

Edit .env:

GHL_API_KEY=your_private_integration_token_here
GHL_LOCATION_ID=your_location_id_here

Build:

npm run build

3. Connect to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "your_private_integration_token",
        "GHL_LOCATION_ID": "your_location_id",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Restart Claude Desktop. You should see GHL tools available.

4. Connect to N8N (HTTP Mode)

Start the server in HTTP mode:

TRANSPORT=http PORT=3001 GHL_API_KEY=your_token GHL_LOCATION_ID=your_id node dist/index.js

In N8N:

1. Add an MCP Client node
2. Set URL to http://localhost:3001/mcp
3. Set transport to HTTP Streamable
4. Use the GHL tools in your workflows

5. Connect to Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["./ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "your_token",
        "GHL_LOCATION_ID": "your_id"
      }
    }
  }
}

Available Tools (60+)

Contacts (15 tools)

Conversations & Messaging (6 tools)

Calendars & Appointments (8 tools)

Opportunities & Pipelines (7 tools)

Payments & Invoices (9 tools)

Other Tools (15+ tools)

Architecture

ghl-mcp-server/
├── src/
│   ├── index.ts              # Entry point (stdio + HTTP transport)
│   ├── constants.ts          # All GHL API endpoints & config
│   ├── types.ts              # TypeScript interfaces
│   ├── services/
│   │   └── api-client.ts     # Auth, rate limiting, error handling
│   └── tools/
│       ├── contacts.ts       # Contact management tools
│       ├── conversations.ts  # Messaging tools
│       ├── calendars.ts      # Calendar & appointment tools
│       ├── opportunities.ts  # Pipeline & deal tools
│       └── business.ts       # Payments, invoices, workflows, etc.
├── dist/                     # Compiled JS
├── package.json
├── tsconfig.json
└── .env.example

Rate Limits

The server includes built-in rate limiting matching GHL's limits:

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

The server automatically queues and retries when limits are approached.

Error Handling

All tools return actionable error messages with hints:

• 401: Check your API key (must be Private Integration Token)
• 403: Missing scopes — edit your Private Integration in GHL Settings
• 404: Resource not found — check the ID
• 422: Validation error with details
• 429: Rate limit — automatic retry

License

MIT — Built by Saurabh K Shah (https://saurabhshah.com)