GoHighLevel MCP Server

Connect Claude and automation clients to GoHighLevel with 269+ tools across 19+ categories.

Overview

This MCP (Model Context Protocol) server connects GoHighLevel to AI clients and automation workflows. It provides comprehensive API coverage for contacts, messaging, opportunities, calendars, marketing, ecommerce, and more.

MAD extensions add multi-tenant routing, safe-mode writes, and an HTTP /mcp endpoint for n8n/NGINX deployments. Use list_tenants for configured tenants and status_self_test for a full health report.

Hosted access is available through the GHL Agent Framework (ask for access).

Project Notice

• Foundation layer that exposes full sub-account API access via MCP.
• Designed for builders to extend, modularize, and ship custom solutions.
• Requires strict safety and permission controls before production use.
• Not intended for resale without added value or productization.

GoHighLevel API Setup

This project requires a Private Integrations API Key (not a standard API key).

1. Log in to GoHighLevel.
2. Go to Settings → Integrations → Private Integrations.
3. Create a new integration (webhook URL not required).
4. Select scopes for the tools you plan to use.
5. Save and copy the Private API Key.
6. Copy your Location ID from Settings → Company → Locations.

Suggested scopes

• contacts.readonly, contacts.write
• conversations.readonly, conversations.write
• opportunities.readonly, opportunities.write
• calendars.readonly, calendars.write
• locations.readonly, locations.write
• workflows.readonly
• campaigns.readonly
• blogs.readonly, blogs.write
• users.readonly
• custom_objects.readonly, custom_objects.write
• invoices.readonly, invoices.write
• payments.readonly
• products.readonly, products.write

Quick Start

# Clone
git clone https://github.com/MADPANDA3D/GHL-MCP.git
cd GHL-MCP

# Install
npm install

# Configure
cp .env.example .env

# Build
npm run build

# Run
npm start

Environment Configuration

# Single-tenant (legacy)
GHL_API_KEY=your_private_integrations_api_key_here
GHL_BASE_URL=https://services.leadconnectorhq.com
GHL_LOCATION_ID=your_location_id_here
NODE_ENV=production

# Multi-tenant (recommended)
TENANT_LIST=MAD,INV,SNM
TENANT_MAD_API_KEY=your_mad_private_key
TENANT_MAD_LOCATION_ID=your_mad_location_id
TENANT_MAD_NAME=MADPANDA3D
TENANT_INV_API_KEY=your_inv_private_key
TENANT_INV_LOCATION_ID=your_inv_location_id
DEFAULT_TENANT_ID=MAD

# Routing + safety
PORT=8000
MCP_SERVER_PORT=8088
MCP_AUTO_ROUTE_BY_LOCATION=true
MCP_STRICT_TENANT_DEFAULT=true
MCP_SAFE_MODE=true
MCP_READ_ONLY=false
MCP_TOOL_ALLOWLIST=
MCP_TOOL_BLOCKLIST=

# Tenant intake forms (returned by list_tenants)
TENANT_FORM_URL=https://your-n8n-form-url
TENANT_FORM_TEST_URL=https://your-n8n-test-form-url

# Agency access (optional)
AGENCY_API_KEY=your_agency_key
AGENCY_COMPANY_ID=your_agency_company_id

Multi-tenant .secrets

If a .secrets file exists, the server loads it automatically. Prefix each line with a tenant ID:

MAD GHL_API_KEY=your_mad_private_key
MAD GHL_LOCATION_ID=your_mad_location_id

INV GHL_API_KEY=your_inv_private_key
INV GHL_LOCATION_ID=your_inv_location_id

This maps to TENANT_<PREFIX>_API_KEY and TENANT_<PREFIX>_LOCATION_ID. For per-tenant read-only mode, set TENANT_<PREFIX>_READ_ONLY=true or TENANT_<PREFIX>_MODE=readonly.

Routing & Safety Defaults

• list_tenants shows configured tenants and optional intake form URLs.
• current_context / whoami show resolved routing context.
• resolve_tenant_by_location auto-routes by locationId when enabled.
• Safe mode requires confirmApply for destructive tools and auto-enables dryRun where supported.
• Use status_self_test for a routing + read + dry-run write report.

Features

• Full GoHighLevel sub-account API access via MCP
• 269+ tools across 19+ categories
• Claude Desktop and HTTP MCP support
• Multi-tenant routing via .secrets or TENANT_* envs
• Auto-route by locationId with strict tenant checks
• Safe-mode writes with confirmApply and dryRun defaults
• Health checks via status_self_test and spec_gap_checklist
• TypeScript codebase with tests and tooling
• Multi-platform deployment (Vercel, Railway, Render, Docker)

Tool Catalog

Tool categories (269 total)

• Contact Management (31)
• Messaging & Conversations (20)
• Blog Management (7)
• Opportunity Management (10)
• Calendar & Appointments (14)
• Email Marketing (5)
• Location Management (24)
• Email Verification (1)
• Social Media Management (17)
• Media Library (3)
• Custom Objects (9)
• Association Management (10)
• Custom Fields V2 (8)
• Workflow Management (1)
• Survey Management (2)
• Store Management (18)
• Products Management (10)
• Payments Management (20)
• Invoices & Billing (39)

Usage Examples

Claude Desktop workflow ideas

• Customer communication workflow
• Sales pipeline updates and follow-ups
• Business intelligence reporting
• Ecommerce operations automation
• Social media scheduling
• Marketing campaign orchestration

Deployment

Deployment options

Vercel

• Build command: npm run build
• Start command: npm start
• Use vercel.json to route to dist/http-server.js

Railway

• Railway detects the Dockerfile automatically
• Add environment variables in the Railway dashboard

Render

• Build command: npm run build
• Start command: npm start

Docker

docker build -t mad-mcp-ghl .
docker run -p 8000:8000 \
  -e GHL_API_KEY=your_key \
  -e GHL_BASE_URL=https://services.leadconnectorhq.com \
  -e GHL_LOCATION_ID=your_location_id \
  mad-mcp-ghl

# Multi-tenant + n8n/NGINX network
docker run -d --name mad-mcp-ghl \
  --network npm_default \
  -p 8088:8088 \
  -e MCP_SERVER_PORT=8088 \
  -v $(pwd)/.secrets:/app/.secrets \
  -e DOTENV_CONFIG_PATH=/app/.secrets \
  mad-mcp-ghl

# GHCR image
docker pull ghcr.io/madpanda3d/mad-mcp-ghl:latest
docker run -p 8000:8000 --env-file .env ghcr.io/madpanda3d/mad-mcp-ghl:latest

Claude Desktop Integration

MCP configuration

{
  "mcpServers": {
    "ghl-mcp-server": {
      "command": "node",
      "args": ["path/to/ghl-mcp-server/dist/server.js"],
      "env": {
        "GHL_API_KEY": "your_private_integrations_api_key",
        "GHL_BASE_URL": "https://services.leadconnectorhq.com",
        "GHL_LOCATION_ID": "your_location_id"
      }
    }
  }
}

HTTP MCP

Use the streamable HTTP endpoint:

YOUR_DEPLOYMENT_URL/mcp

SSE is still available at /sse if you need it.

Architecture

Project structure

ghl-mcp-server/
├── src/
│   ├── clients/
│   ├── tools/
│   ├── types/
│   ├── tenants/
│   ├── utils/
│   ├── server.ts
│   └── http-server.ts
├── tests/
├── api/
├── docker/
├── dist/
├── docs/
├── package.json
├── tsconfig.json
├── jest.config.js
├── vercel.json
├── railway.json
├── Dockerfile
└── README.md

Security & Best Practices

Guidelines

• Never commit API keys to version control.
• Use environment variables for all secrets.
• Implement request rate limiting for production.
• Monitor API usage and apply backoff where needed.
• Restrict permissions to the minimum required scopes.

Troubleshooting

Common issues

Health checks Use the status_self_test tool to validate routing, one read call, and a dry-run write.

Build failures

rm -rf node_modules package-lock.json dist/
npm install
npm run build

API connection issues

curl -H "Authorization: Bearer YOUR_PRIVATE_INTEGRATIONS_API_KEY" \
  https://services.leadconnectorhq.com/locations/YOUR_LOCATION_ID

Memory issues

node --max-old-space-size=8192 dist/server.js

Technical Specs

System requirements

• Node.js 18+ (LTS)
• Minimum 512MB RAM (1GB+ recommended)
• Stable network for GoHighLevel API access

Contributing

Workflow

# Fork and clone
# Create a feature branch
# Add tests
npm test

# Commit and push
# Open a PR

License

MIT.

Support

Affiliate Links

Services I use (affiliate)

Using these links helps support continued development.

Hostinger VPS

• KVM 1
• KVM 2
• KVM 4
• KVM 8

Cloud Hosting

• Cloud Economy
• Cloud Professional
• Cloud Enterprise

Web Hosting

• Premium
• Business

Website Builder

• Premium
• Business

Agency Hosting

• Startup
• Growth
• Professional

Email

• Business Pro
• Business Premium

Reach

• Reach 500
• Reach 1000
• Reach 2500

Contact

Open an issue in MADPANDA3D/GHL-MCP.

MADPANDA3D