@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

• Log into GoHighLevel → Settings → Private Integrations
• Click Create New Integration
• Name it (e.g., "Claude MCP Server")
• Select all scopes you need (contacts, conversations, calendars, payments, etc.)
• Copy the Private Integration Token
• 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:

• Add an MCP Client node
• Set URL to http://localhost:3001/mcp
• Set transport to HTTP Streamable
• 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)