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)

| Tool | Description | |------|-------------| | ghl_search_contacts | Search contacts by query, tags, filters | | ghl_get_contact | Get contact by ID | | ghl_create_contact | Create new contact | | ghl_update_contact | Update existing contact | | ghl_delete_contact | Delete contact | | ghl_upsert_contact | Create or update by email/phone | | ghl_add_contact_tags | Add tags to contact | | ghl_remove_contact_tags | Remove tags from contact | | ghl_get_contact_notes | Get contact notes | | ghl_create_contact_note | Add note to contact | | ghl_delete_contact_note | Delete a note | | ghl_get_contact_tasks | Get contact tasks | | ghl_create_contact_task | Create task for contact | | ghl_update_contact_task | Update task | | ghl_add_contact_to_workflow | Add contact to workflow | | ghl_remove_contact_from_workflow | Remove from workflow |

Conversations & Messaging (6 tools)

| Tool | Description | |------|-------------| | ghl_search_conversations | Search conversation threads | | ghl_get_conversation | Get conversation details | | ghl_get_messages | Get messages in a thread | | ghl_send_message | Send SMS/Email/WhatsApp/etc. | | ghl_cancel_scheduled_message | Cancel scheduled message | | ghl_update_conversation | Update conversation status |

Calendars & Appointments (8 tools)

| Tool | Description | |------|-------------| | ghl_list_calendars | List all calendars | | ghl_get_calendar | Get calendar details | | ghl_get_free_slots | Get available booking slots | | ghl_get_events | Get appointments/events | | ghl_create_event | Create appointment | | ghl_update_event | Update appointment | | ghl_delete_event | Delete appointment | | ghl_create_calendar | Create new calendar |

Opportunities & Pipelines (7 tools)

| Tool | Description | |------|-------------| | ghl_search_opportunities | Search deals | | ghl_get_opportunity | Get deal details | | ghl_create_opportunity | Create new deal | | ghl_update_opportunity | Update deal / move stages | | ghl_delete_opportunity | Delete deal | | ghl_update_opportunity_status | Change deal status | | ghl_list_pipelines | List pipelines & stages |

Payments & Invoices (9 tools)

| Tool | Description | |------|-------------| | ghl_list_orders | List payment orders | | ghl_get_order | Get order details | | ghl_list_transactions | List transactions | | ghl_list_subscriptions | List subscriptions | | ghl_list_invoices | List invoices | | ghl_get_invoice | Get invoice details | | ghl_create_invoice | Create invoice | | ghl_send_invoice | Email invoice to contact | | ghl_void_invoice | Void an invoice |

Other Tools (15+ tools)

| Tool | Description | |------|-------------| | ghl_list_workflows | List all workflows | | ghl_list_custom_fields | List custom fields | | ghl_create_custom_field | Create custom field | | ghl_get_location | Get location details | | ghl_get_location_tags | Get location tags | | ghl_create_location_tag | Create new tag | | ghl_search_users | Search team members | | ghl_list_forms | List forms | | ghl_get_form_submissions | Get form submissions | | ghl_list_surveys | List surveys | | ghl_list_campaigns | List campaigns | | ghl_list_social_posts | List social posts | | ghl_create_social_post | Create/schedule social post | | ghl_list_social_accounts | List connected social accounts | | ghl_list_funnels | List funnels/websites | | ghl_list_products | List products | | ghl_list_blogs | List blogs | | ghl_list_links | List trigger links |

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)