GHL Command — GoHighLevel MCP Server

Full GoHighLevel API access for Claude. 219 tools across 43 modules — manage contacts, conversations, pipelines, calendars, funnels, workflows, invoices, custom objects, webhooks, and more. Includes full workflow builder, funnel/page editor, form builder, pipeline builder, bulk operations, account export, and workflow cloning — capabilities no other GHL tool offers. Multi-tenant: one install can run the workflow builder across multiple clients' GHL accounts.

Distributed via npm as @elitedcs/ghl-mcp. Buyers install with one config block — no git, no Node.js setup, no terminal commands. Updates flow automatically (npx @latest re-resolves on every Claude restart).

Works with both the Claude Desktop App and Claude Code terminal — your choice.

License required. Get it at ghlcommand.com — $97/mo, covering UNLIMITED GoHighLevel sub-accounts on up to 3 machines (never billed per account). 30-day time-back guarantee: save 5+ hours on one client build or your first month back.

Built by Elite DCs, LLC.

What Buyers Say

"I've already set it up, I'm using it and it works perfectly!" — Andres G., paying customer

"Wow! That makes me VERY happy. Given what you've built (I can't wait to test it), I would have been willing to run it on Claude Desktop lol. But on my droplet, as an actual AI skill, even better." — Garret W., paying customer (running it headless on a Linux droplet)

"That worked. Thank you." — Ryan T., paying customer (bug reported Monday, fix shipped as v3.23.0 Tuesday, confirmed Tuesday)

"Thank you, Jerry. You're a star." — Frankie B.

30+ releases on npm since launch (v3.6.0 → v3.34.0). Bugs get fixed in days, not quarters.

What Makes This Different

Most GHL integrations give you read access and basic CRUD. This server goes far beyond that — it includes capabilities that don't exist anywhere else, built on reverse-engineered internal APIs that GHL's public API doesn't expose.

| Exclusive Feature | Why It Matters | |---|---| | Programmatic Workflow Builder | The only tool on the market that can create, edit, and publish GHL workflows via code. GHL's public API has no workflow write endpoints — this uses their internal backend API (the same one their UI calls) to give Claude full workflow CRUD. Build entire automation sequences from a conversation. | | Deep Workflow Cloning | Clone any workflow with full UUID remapping — every action, trigger, branch, and internal reference gets new IDs. No other tool can duplicate a workflow programmatically without ID collisions. | | Funnel & Page Editor | Read and edit funnel page content — sections, elements, rows, CSS, tracking codes. Goes beyond the public API's list-only access. | | Form Builder | Full form CRUD including field management, conditional logic, and auto-responder configuration via internal API. | | Pipeline Builder | Create, edit, and delete pipelines and stages via internal API. The public API only lists pipelines — this lets Claude build them. | | Template Deployment | Deploy a complete sub-account setup (tags, custom fields, pipelines, workflows, forms) from a single template. Set up a new client in minutes instead of hours. | | Multi-Sub-Account Token Registry | Register multiple sub-accounts with their own API keys. Switch locations mid-session and the API key swaps automatically — no restart needed. | | Full Account Export & Diff | Export an entire sub-account to JSON or compare two locations side-by-side. Useful for auditing, migration, and quality control. |

Everything else — CRM, conversations, calendars, invoices, bulk ops — works through GHL's official public API v2 with full read/write access.

What It Does

This MCP (Model Context Protocol) server connects Claude directly to GoHighLevel's API v2. Once installed, Claude can read and write to your GHL account — no browser, no Zapier, no middleware. Use it from the Claude Desktop App (no terminal needed) or from Claude Code in the terminal.

| Capability | What Claude Can Do | |---|---| | CRM | Search, create, update, and delete contacts. Manage tags, notes, tasks. | | Conversations | Read message threads, send SMS/email/WhatsApp, update message status. | | Pipeline | Create and manage opportunities. Move deals through stages. | | Scheduling | Check availability, book appointments, manage calendars. | | Automation | Full workflow builder — create, read, edit, and publish workflows. See every action, trigger, condition, and branch. Clone workflows with deep ID remapping. | | Marketing | Funnel/page editor — read and edit existing funnel page content (sections, elements, CSS). Full form builder — read/edit all fields, conditional logic, auto-responder. | | Pipelines | Full pipeline builder — create, edit, delete pipelines. Add, remove, rename, reorder stages. | | Bulk Ops | Batch tag, untag, update fields, enroll in workflows, or delete contacts — all rate-limited. | | Backup | Export entire sub-account to JSON. Compare two locations side-by-side for auditing. | | Multi-Location | Switch between sub-accounts mid-session. Token registry stores per-location API keys for seamless switching. | | Billing | Create/send/void invoices, record payments, view orders and subscriptions. | | Content | Manage blog posts, social media posts, courses, media files. | | Custom Objects | Full CRUD on custom object schemas and records. Manage associations. | | Estimates & Coupons | Create/send estimates, manage promo codes. | | Webhooks | Create and manage webhook subscriptions. | | Documents | List, send, and manage documents/contracts. | | Admin | View/update sub-accounts, manage custom fields, custom values, location tags, users. |

Quick Start (5 minutes)

1. Buy a license

ghlcommand.com — $97/mo, every sub-account you manage. License key arrives by email within 1-2 minutes.

2. Install in Claude Desktop App

Open Claude Desktop. Click Claude menu (top-left) → Settings... → Developer → Edit Config. Paste this block (or merge into your existing mcpServers if you have other MCP servers):

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@elitedcs/ghl-mcp@latest"]
    }
  }
}

Save the file. Quit Claude completely (Cmd+Q on Mac) and reopen.

Claude Code (terminal) instead? One command:

claude mcp add --scope user -t stdio ghl -- npx -y @elitedcs/ghl-mcp@latest

Then restart Claude Code.

3. Activate

After restart, GHL Command is loaded but locked. Type this in Claude (replace the four placeholders with your real values):

Run setup_ghl_mcp to activate GHL Command:
  email: YOUR_PURCHASE_EMAIL
  license_key: YOUR_LICENSE_KEY
  ghl_api_key: YOUR_GHL_API_KEY
  ghl_location_id: YOUR_LOCATION_ID

Approve the tool call. Server validates your license, verifies your GHL credentials, writes them to a per-user config file. Quit Claude one more time and reopen — the full core toolset is now unlocked (219 tools total with the optional Workflow Builder Firebase add-on).

4. Try it

"List my GHL contacts"
"Show my pipelines"
"What calendars do I have?"

Full step-by-step setup with screenshots: elitedcs.com/ghl-mcp-setup-guide.html

Get Your GHL API Key

CRITICAL: Sub-Account Level Only

Private Integrations in GHL are scoped to individual sub-accounts, NOT to the agency level. You must create a separate Private Integration inside each sub-account you want to connect. An API key created in Sub-Account A will return 403 Forbidden if you try to use it with Sub-Account B's Location ID.

Your API key can only be copied ONCE — at the moment you create the integration. After you leave that screen, the key is permanently masked and cannot be retrieved. If you lose it, you must delete the integration and create a new one.

1. Log into GoHighLevel
2. Switch into the specific sub-account you want to connect (not the agency view)
3. Go to Settings > Integrations
4. Click Private Integrations > Create Private Integration
5. Name it Claude Code MCP
6. Enable all scopes/permissions you want Claude to access
7. Immediately copy the API Key and pass it to setup_ghl_mcp as ghl_api_key — you will not be able to see it again

Find Your Location ID

Your Location ID (sub-account ID) is in the GHL URL when you'''re inside a sub-account:

https://app.gohighlevel.com/v2/location/YOUR_LOCATION_ID/dashboard

Enable Workflow Builder (Optional)

The builder + cloner + validator tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, validate_workflow) use GHL'''s internal API and require Firebase credentials. Without them, the other 163 tools work fine — you just won'''t have workflow/funnel/form/pipeline editing.

Grab the three values from your GHL browser session, then re-run setup_ghl_mcp with them:

1. Open app.gohighlevel.com in Chrome (or any Chromium browser), log in.
2. Open DevTools (Cmd+Opt+I on Mac, F12 on Windows) → Application tab → IndexedDB in the left panel.
3. Expand: firebaseLocalStorageDb → firebaseLocalStorage.
4. Find the row whose key starts with firebase:authUser:.
5. The part between authUser: and :[DEFAULT] is your ghl_firebase_api_key (starts with AIza).
6. Inside that row's value object: uid is your ghl_user_id.
7. Inside value.stsTokenManager.refreshToken is your ghl_firebase_refresh_token.

Then in Claude:

Re-run setup_ghl_mcp with workflow builder:
  email: YOUR_PURCHASE_EMAIL
  license_key: YOUR_LICENSE_KEY
  ghl_api_key: YOUR_GHL_API_KEY
  ghl_location_id: YOUR_LOCATION_ID
  ghl_user_id: FROM_STEP_6
  ghl_firebase_api_key: FROM_STEP_5
  ghl_firebase_refresh_token: FROM_STEP_7

Firebase refresh tokens can rotate. If workflow tools stop working after a few weeks, repeat steps 1–7 and re-run setup_ghl_mcp with fresh values.

Working in Clients' Accounts (Multi-Tenant)

The public-API tools work in any sub-account you have a Private Integration key for. The workflow builder (and every Firebase-gated tool) is different: GHL Firebase refresh tokens are company-scoped, so your own token can't build workflows inside a client's GHL — even if you're an admin user there. Without the client's own Firebase, those accounts are effectively read-only.

To unlock full builder access across multiple clients from one install:

1. Register the client's sub-account key so the public API works there:

   register_location
     locationId: CLIENT_LOCATION_ID
     name: "Client Name"
     apiKey: pit-...   (a Private Integration created INSIDE the client's sub-account)

   This auto-detects and stores the owning companyId.

2. Capture the client's Firebase values from a browser session logged into their account (same DevTools steps 1–7 above, but while viewing the client's GHL).

3. Register the client's company Firebase:

   register_company_firebase
     companyId: CLIENT_COMPANY_ID         (best-effort — see note)
     name: "Client Name"
     ghl_firebase_refresh_token: FROM_STEP_7
     ghl_user_id: FROM_STEP_6
     test_location_id: CLIENT_LOCATION_ID  (optional — runs a live check that it works)

   companyId is best-effort. GHL's agency-URL company ID is a different identifier than the internal one used for sub-accounts. The tool decodes the company ID the Firebase token itself authenticates as and stores the entry under that, so you don't have to track down the exact internal ID — pass whatever you have (e.g. from register_location's output) and it self-corrects.

4. Switch and build: switch_location CLIENT_LOCATION_ID swaps both the API key and the Firebase auth automatically. The workflow builder now operates in the client's account. Switching back to your own location restores your home Firebase.

list_registered_locations shows every location, its company, and which companies have Firebase wired up. health_check reports the active company. Rotated tokens are saved back to the correct client, never overwriting your own.

Server / Headless Deployment

GHL Command runs headless — Linux droplet, container, or behind an MCP gateway (MetaMCP, etc.). One license covers every GoHighLevel sub-account you manage, on up to 3 of your own machines. No per-account fees. A server counts as one machine; restarts never consume extra activations.

Highlights (full guide: docs/HEADLESS.md):

• Scriptable multi-account setup — pre-seed the documented .ghl-tokens.json, or use the CLI in a Dockerfile/entrypoint:

  npx -y @elitedcs/ghl-mcp cli register-location --location-id XXXX --api-key pit-... --name "Account"
  npx -y @elitedcs/ghl-mcp cli register-company-firebase --company-id YYYY --refresh-token ... --user-id ...
  npx -y @elitedcs/ghl-mcp cli register-agency-key --api-key pit-...

• Persistent config dir — set GHL_MCP_CONFIG_DIR=/data/ghl-mcp (absolute path) on a mounted volume so auto-rotated Firebase tokens survive container restarts.
• Firebase is per-company, not per-sub-account — one credential set covers all sub-accounts under a company.
• Node 20+, graceful SIGTERM shutdown, GHL_MCP_DISABLE_UPDATE_CHECK=1 for air-gapped boxes. Transport is stdio (your gateway supervises it as a child process); an HTTP serve mode is on the roadmap.

Tools

v3.10.0 adds Email Templates (list_email_templates, create_email_template, update_email_template) — Claude can now create new HTML email templates and save content into them via the public API. Templates power both standalone marketing emails and workflow email actions. Delete + rename remain UI-only (no public-API endpoint exists).

CRM & Contacts (15 tools)

| Tool | What It Does | |---|---| | search_contacts | Search contacts by name, email, phone, or tag | | get_contact | Get full contact details by ID | | create_contact | Create a new contact | | update_contact | Update contact fields | | delete_contact | Delete a contact | | upsert_contact | Create or update a contact (match by email/phone) | | add_contact_tags | Add tags to a contact | | remove_contact_tags | Remove tags from a contact | | get_contact_tasks | List tasks for a contact | | create_contact_task | Create a task on a contact | | get_contact_notes | List notes on a contact | | create_contact_note | Add a note to a contact | | get_contact_appointments | List a contact's appointments | | add_contact_to_workflow | Add a contact to a workflow | | remove_contact_from_workflow | Remove a contact from a workflow |

Conversations & Messaging (8 tools)

| Tool | What It Does | |---|---| | search_conversations | Search conversation threads | | get_conversation | Get a specific conversation | | create_conversation | Start a new conversation | | get_messages | Read messages in a conversation | | send_message | Send SMS, email, or WhatsApp message | | add_inbound_message | Log an inbound message | | update_message_status | Update read/unread status | | get_message | Get a specific message |

Opportunities & Pipelines (7 tools)

| Tool | What It Does | |---|---| | search_opportunities | Search deals across pipelines | | get_opportunity | Get opportunity details | | create_opportunity | Create a new deal | | update_opportunity | Update deal fields or move stages | | delete_opportunity | Delete a deal | | update_opportunity_status | Change opportunity status (won/lost/open) | | get_pipelines | List all pipelines and their stages |

Calendars & Scheduling (11 tools)

| Tool | What It Does | |---|---| | get_calendars | List all calendars | | get_calendar | Get calendar details | | create_calendar | Create a new calendar | | update_calendar | Update calendar settings | | delete_calendar | Delete a calendar | | get_free_slots | Check available time slots | | get_calendar_events | List events on a calendar | | get_appointment | Get appointment details | | create_appointment | Book an appointment | | update_appointment | Update an appointment | | delete_appointment | Cancel an appointment |

Locations & Sub-Accounts (15 tools)

| Tool | What It Does | |---|---| | get_location | Get sub-account details | | update_location | Update sub-account settings | | search_locations | Search locations | | get_location_tags | List all tags in a location | | create_location_tag | Create a new tag | | update_location_tag | Update an existing tag | | delete_location_tag | Delete a tag | | get_custom_fields | List all custom fields | | create_custom_field | Create a new custom field | | update_custom_field | Update a custom field | | delete_custom_field | Delete a custom field | | get_custom_values | List all custom values | | create_custom_value | Create a new custom value | | update_custom_value | Update a custom value | | delete_custom_value | Delete a custom value |

Custom Objects (7 tools)

| Tool | What It Does | |---|---| | list_custom_objects | List all custom object schemas | | get_custom_object | Get a custom object schema by key | | search_custom_object_records | Search records of a custom object | | get_custom_object_record | Get a single record by ID | | create_custom_object_record | Create a new record | | update_custom_object_record | Update an existing record | | delete_custom_object_record | Delete a record |

Associations (3 tools)

| Tool | What It Does | |---|---| | list_associations | List associations for a custom object record | | create_association | Link a record to a contact/opportunity/other record | | delete_association | Remove an association |

Invoices & Billing (8 tools)

| Tool | What It Does | |---|---| | list_invoices | List all invoices | | get_invoice | Get invoice details | | create_invoice | Create a new invoice | | update_invoice | Update an invoice | | send_invoice | Send invoice to recipient | | void_invoice | Void an invoice | | record_invoice_payment | Record a payment against an invoice | | delete_invoice | Delete an invoice |

Estimates (6 tools)

| Tool | What It Does | |---|---| | list_estimates | List estimates/quotes | | get_estimate | Get estimate details | | create_estimate | Create a new estimate | | update_estimate | Update an estimate | | delete_estimate | Delete an estimate | | send_estimate | Send an estimate to a contact |

Coupons (5 tools)

| Tool | What It Does | |---|---| | list_coupons | List all coupons/promo codes | | get_coupon | Get coupon details | | create_coupon | Create a new coupon | | update_coupon | Update a coupon | | delete_coupon | Delete a coupon |

Webhooks (5 tools)

| Tool | What It Does | |---|---| | list_webhooks | List all webhook subscriptions | | get_webhook | Get webhook details | | create_webhook | Create a new webhook | | update_webhook | Update a webhook | | delete_webhook | Delete a webhook |

Documents (4 tools)

| Tool | What It Does | |---|---| | list_documents | List documents and contracts | | get_document | Get document details and signature status | | delete_document | Delete a document | | send_document | Send a document for e-signature |

Payments (4 tools)

| Tool | What It Does | |---|---| | get_orders | View all orders | | get_order | Get order details | | get_subscriptions | List active subscriptions | | get_transactions | View transaction history |

Workflow Builder (9 tools) — Internal API

This is the flagship feature. GHL's public API has zero workflow write endpoints. These tools use GHL's internal backend API — the same API their own UI calls — reverse-engineered to give Claude full workflow CRUD. No other GHL integration, Zapier connector, or third-party tool can create or edit workflows programmatically. Requires additional Firebase auth setup (see "Enable Workflow Builder" in Quick Start above).

| Tool | What It Does | |---|---| | list_workflows_full | List all workflows with full metadata, versions, and permissions | | get_workflow_full | Get complete workflow internals: every action, trigger, condition, if/else branch, email template, SMS body | | create_workflow | Create a new workflow from scratch (starts as draft) | | update_workflow_actions | Add, edit, or remove actions, triggers, and branches in an existing workflow | | delete_workflow_full | Permanently delete a workflow | | publish_workflow | Publish a draft workflow to make it active | | get_trigger_registry | Discover GHL's marketplace trigger apps (Zoom, WooCommerce, Shopify, etc.) and their available trigger templates | | validate_workflow | Pre-flight validation: scans every action and trigger for references to pipelines, stages, custom fields, users, and other workflows; verifies each ID exists. Catches the silent-failure bug where invalid IDs make GHL skip subsequent actions | | build_goal_event | Build a correctly-shaped goal-event node. Goals sit inline in the action chain — when the goal condition fires (e.g., review_request_clicked), the configured action runs (default: exit the workflow). Returns a workflow_goal node ready to wire into your actions array |

What you can build: Complete automation sequences — lead nurture drip campaigns, appointment reminder sequences, onboarding flows, re-engagement workflows, internal notification chains, conditional exit workflows with goal events. Tell Claude what you want and it builds the workflow action by action.

Supported action types: sms, email, add_contact_tag, remove_contact_tag, update_contact_field, wait, if_else, webhook, create_opportunity, custom_code, add_notes, internal_notification, task_notification, remove_from_workflow, workflow_goal, and more.

Supported trigger types: All 57 native GHL trigger types are deeply typed with their own Zod variant. 42 have full field-path documentation (opportunity_*, form_submission, contact_changed, survey_submission, birthday_reminder, mailgun_email_event, and 36 others). 4 have partial docs, 2 are fieldless by design, 9 have type-only discrimination pending field-path capture. A permissive fallback handles any future trigger types GHL ships, so reads never crash. Plus 434 marketplace trigger entries across 85 third-party apps — query them via get_trigger_registry.

Pipeline Builder (5 tools) — Internal API

Also uses GHL's internal API. The public API only lists pipelines — this lets Claude create, edit, and delete pipelines and their stages.

| Tool | What It Does | |---|---| | list_pipelines_full | List all pipelines with full stage details, positions, and display settings | | get_pipeline_full | Get a single pipeline with complete stage configuration | | create_pipeline | Create a new pipeline with stages | | update_pipeline | Update name, add/remove/rename/reorder stages | | delete_pipeline | Permanently delete a pipeline |

Bulk Operations (5 tools)

| Tool | What It Does | |---|---| | bulk_add_tags | Add tags to multiple contacts at once (rate-limited) | | bulk_remove_tags | Remove tags from multiple contacts (rate-limited) | | bulk_update_contacts | Update the same fields on multiple contacts (rate-limited) | | bulk_add_to_workflow | Enroll multiple contacts into a workflow (rate-limited) | | bulk_delete_contacts | Delete multiple contacts (rate-limited, requires safety confirmation) |

Account Export & Comparison (2 tools)

| Tool | What It Does | |---|---| | export_account | Full sub-account backup — contacts, pipelines, workflows, funnels, forms, fields, tags, calendars, users | | compare_locations | Side-by-side diff of two sub-accounts for auditing or migration |

Location Switcher & Token Registry (6 tools)

| Tool | What It Does | |---|---| | get_current_location | Show which sub-account is active | | switch_location | Switch to a different sub-account mid-session (auto-swaps API key from registry) | | list_available_locations | List all accessible sub-accounts | | register_location | Add a sub-account and its API key to the token registry | | unregister_location | Remove a sub-account from the token registry | | list_registered_locations | List all sub-accounts stored in the token registry |

Workflow Cloner (1 tool)

Deep-clones a workflow with full UUID remapping. Every action, trigger, branch, and internal cross-reference gets a new unique ID. GHL has no built-in way to duplicate a workflow programmatically — this is the only tool that can.

| Tool | What It Does | |---|---| | clone_workflow | Deep clone a workflow with new UUIDs for all actions, triggers, and references |

Template Deployer (3 tools)

Deploy a complete sub-account setup from a pre-built template — tags, custom fields, pipelines, workflows, and forms — in one step. Claude walks the user through a questionnaire, then deploys everything. Includes dry-run mode to preview changes before applying.

| Tool | What It Does | |---|---| | list_templates | List available setup templates (clinic, med spa, dental, etc.) | | get_template_questionnaire | Get the questionnaire for a template — present to user conversationally | | deploy_template | Deploy a complete sub-account setup from a template (tags, fields, pipelines, workflows, forms). Supports dry-run mode. |

Setup & Diagnostics (3 tools)

| Tool | What It Does | |---|---| | get_mcp_version | Check installed version against the latest published to npm. Confirms an upgrade landed after restarting Claude. Available even before GHL credentials are configured. | | health_check | Run a full health check: npm registry + version status, GHL API key validity, default location reachability, Firebase auth status, token registry presence. Use when something feels broken. | | enable_workflow_builder | Add Firebase credentials to an existing install to unlock 49 additional Firebase-gated tools (workflow builder, funnel builder, form builder, pipeline builder, workflow cloner, smart lists, reputation, email campaigns, email templates, memberships, validate_workflow). No need to re-enter license / API key / location ID. Run this any time after the basic setup, on the buyer's schedule. |

Other Modules

| Module | Tools | What It Does | |---|---|---| | Social Planner | 5 | Create, list, delete posts, view connected accounts | | Businesses | 5 | Full CRUD on business entities | | Blogs | 5 | Posts, authors, categories, URL slugs | | Funnels (public API) | 2 | List funnels and their pages | | Forms (public API) | 2 | List forms and view submissions | | Surveys | 2 | List surveys and view submissions | | Users | 2 | List and view team members | | Media | 2 | Browse and delete media files | | Campaigns | 1 | List campaigns | | Workflows (public API) | 1 | List all workflows | | Courses | 1 | List courses | | Emails | 1 | List email campaigns | | Trigger Links | 1 | List trigger links |

How It Works

┌──────────────────┐   ┌──────────────────┐
│  Claude Desktop  │   │  Claude Code     │
│  App (GUI)       │   │  (Terminal)      │
└────────┬─────────┘   └────────┬─────────┘
         │                      │
         └──────────┬───────────┘
                    │ MCP Protocol (stdio)
┌───────────────────┴─────────────────────┐
│            GHL MCP SERVER               │
│                                         │
│  ┌──────────┐ ┌──────────┐ ┌────────┐  │
│  │ Contacts │ │ Calendar │ │Invoices│  │
│  │ 15 tools │ │ 11 tools │ │8 tools │  │
│  └────┬─────┘ └────┬─────┘ └───┬────┘  │
│       └─────────────┼───────────┘       │
│              ┌──────┴──────┐            │
│              │  GHL Client │            │
│              └──────┬──────┘            │
├─────────────────────┼───────────────────┤
│                     ↓                   │
│        GoHighLevel API v2               │
│   https://services.leadconnectorhq.com  │
└─────────────────────────────────────────┘

Architecture

• src/index.ts — MCP server entry, startup API key validation, tool registration.
• src/ghl-client.ts — HTTP client for GHL API v2. Returns Promise<unknown> (no generic as T casts). Automatic retry with exponential backoff on 429/5xx/network errors. 30-second timeout with clear error messages.
• src/workflow-builder-client.ts — Internal API client for workflow CRUD. Firebase auth with thread-safe token refresh (promise lock), retry/backoff, Zod-validated WorkflowFull responses, and pre-flight validateActionChain() that catches common action attribute errors before GHL can silently fail.
• src/api-schemas.ts — Zod response schemas for contacts, pipelines, and calendars. Runtime validation on the most-used API paths.
• src/workflow-action-types.ts — Discriminated union types for all 11 documented workflow action types. Compile-time enforcement of action-specific attributes (SMS needs body, email needs subject+html, etc.).
• src/tool-helpers.ts — safeTool() wrapper (automatic try/catch + JSON formatting for 127 tools), response helpers, error formatting.
• src/token-registry.ts — Per-location API key storage, Zod-validated on load with corruption backup.
• src/tools/index.ts — Type-safe registry array. Compiler catches missing tool registrations.
• src/tools/*.ts — One file per GHL domain. Most use safeTool() for zero-boilerplate handlers.

Build System

Uses esbuild for production builds (not tsc). TypeScript 5.9.3 + MCP SDK types cause tsc to run out of memory at 4GB+. esbuild bundles in ~5ms with zero memory issues.

npm run build    # esbuild → dist/index.js (~428KB)
npm run dev      # tsc --watch (type-checking only)

Data Flow

User prompt → Claude Code → MCP tool call → GHL Client → GHL API → JSON response → Claude Code → User

Every tool returns structured JSON. Claude interprets the response and presents it naturally. No data is stored locally — it's a pass-through to GHL's API.

Project Structure

ghl-command-mcp/
├── src/
│   ├── index.ts                   # MCP server entry point + startup validation
│   ├── ghl-client.ts              # GHL API v2 HTTP client (retry/backoff, returns unknown)
│   ├── workflow-builder-client.ts # Internal API client (Firebase auth, Zod-validated responses)
│   ├── workflow-action-types.ts   # Discriminated union types for workflow actions
│   ├── api-schemas.ts             # Zod response schemas for contacts, pipelines, calendars
│   ├── token-registry.ts          # Per-location API key storage (Zod-validated on load)
│   ├── tool-helpers.ts            # safeTool() wrapper, response helpers, error formatting
│   └── tools/
│       ├── index.ts               # Type-safe tool registry (compiler-checked)
│       ├── contacts.ts            # 15 tools — CRM & contact management
│       ├── conversations.ts       # 8 tools — messaging (SMS, email, WhatsApp)
│       ├── opportunities.ts       # 7 tools — pipeline & deal management
│       ├── calendars.ts           # 11 tools — scheduling & appointments
│       ├── locations.ts           # 15 tools — sub-accounts, custom fields/values, tags
│       ├── invoices.ts            # 8 tools — invoicing & payment recording
│       ├── custom-objects.ts      # 7 tools — custom object schema & record CRUD
│       ├── estimates.ts           # 6 tools — estimates/quotes
│       ├── social-planner.ts      # 5 tools — social media management
│       ├── businesses.ts          # 5 tools — business entity management
│       ├── blogs.ts               # 5 tools — blog management
│       ├── coupons.ts             # 5 tools — promo code management
│       ├── webhooks.ts            # 5 tools — webhook subscriptions
│       ├── payments.ts            # 4 tools — orders, subscriptions, transactions
│       ├── documents.ts           # 4 tools — document & contract management
│       ├── associations.ts        # 3 tools — custom object associations
│       ├── funnels.ts             # 2 tools — funnel & page listing
│       ├── forms.ts               # 2 tools — forms & submissions
│       ├── surveys.ts             # 2 tools — surveys & submissions
│       ├── users.ts               # 2 tools — team members
│       ├── media.ts               # 2 tools — media file management
│       ├── campaigns.ts           # 1 tool  — campaign listing
│       ├── workflows.ts           # 1 tool  — workflow listing
│       ├── courses.ts             # 1 tool  — course listing
│       ├── emails.ts              # 1 tool  — email campaign listing
│       ├── trigger-links.ts       # 1 tool  — trigger link listing
│       ├── workflow-builder.ts    # 6 tools — full workflow CRUD (internal API)
│       ├── funnel-builder.ts      # 10 tools — funnel/page builder (internal API)
│       ├── form-builder.ts        # 5 tools — form builder (internal API)
│       ├── pipeline-builder.ts    # 5 tools — pipeline/stage builder (internal API)
│       ├── bulk-operations.ts     # 5 tools — batch contact operations
│       ├── account-export.ts      # 2 tools — backup & location comparison
│       ├── workflow-cloner.ts     # 1 tool  — deep workflow cloning
│       ├── location-switcher.ts   # 6 tools — multi-location support + token registry
│       └── template-deployer.ts   # 3 tools — deploy sub-account from template (Zod-validated)
├── templates/
│   ├── clinic-medspa.json         # Clinic/Med Spa blueprint
│   └── action-schemas.json        # Mandatory workflow action attribute schemas
├── dist/                          # Compiled JavaScript (npm-published bundle)
├── bin/ghl-mcp.js                 # npm bin entry point
├── .github/workflows/publish.yml  # GitHub Actions npm-publish workflow
├── package.json                   # @elitedcs/ghl-mcp
├── tsconfig.json
├── CLAUDE.md                      # Claude Code project instructions
├── CHANGELOG.md
├── CONTRIBUTING.md                # Contributor guide
├── .gitignore
└── README.md
# Legacy (kept for self-hosted dev workflows; buyers don't need these):
# setup.sh, setup-wizard.mjs, start-mcp.example.sh

Known Limitations

These are GHL features the MCP server does not currently support. In most cases, the GHL API either doesn't expose these endpoints or the feature requires browser-level interaction.

| Area | What's Missing | |---|---| | Contact deduplication | No merge or dedup tool. search_contacts can find potential duplicates by name/email/phone, but merging must be done manually in the GHL UI. | | Account auditing | No one-click "find what's broken" scanner. export_account dumps full sub-account data and compare_locations diffs two accounts — Claude can analyze the output to spot issues, but it's not a turnkey audit button. | | SMS/email templates | No template CRUD. You can send messages and build email actions in workflows, but managing reusable message templates isn't supported. | | Payment gateway config | Read-only access to orders, subscriptions, and transactions. No Stripe/payment gateway setup or configuration. | | Phone & call tracking | No call tools. VoIP, call tracking, and phone number management are not available via the API. | | Memberships & communities | Not supported. GHL's membership/community features don't have public API endpoints. | | Reporting & analytics | No dashboard or reporting tools. Use export_account for raw data, but there are no built-in analytics queries. | | Trigger links | List only — no create, update, or delete. | | Campaigns | List only — no create, update, or delete. | | Courses | List only — no create, update, or delete. | | Workflow builder auth | Requires Firebase credentials extracted from browser DevTools. The refresh token may rotate, requiring re-extraction. |

Contributing: If you'd like to help close any of these gaps, see CONTRIBUTING.md.

Security

This MCP server is safe to share via GitHub.

| Concern | How It's Handled | |---|---| | API Keys | Stored in a per-user credentials file (~/Library/Application Support/elitedcs-ghl-mcp/credentials.json on Mac) at chmod 0600. Never in code, never committed. | | License validation | Checked at setup_ghl_mcp against the elitedcs.com license server, then cached as a signed attestation (~30 days). The server renews the attestation in the background as expiry approaches — never per-request, and your GHL keys are never sent to us. | | Multi-user | Each user brings their own license key + GHL API key. Complete account isolation. | | Scope | The server only talks to GHL's API, the elitedcs.com license server (setup + periodic attestation renewal), and npm's registry (startup version banner — GHL_MCP_DISABLE_UPDATE_CHECK=1 to disable). No filesystem access beyond its config dir, no shell commands. | | Permissions | Controlled by your GHL Private Integration scopes. Disable what you don't need. |

Reliability & Type Safety

This server has been through a rigorous, multi-pass audit for production reliability (v2.4.0–v2.7.0). Here's what's in place:

| Layer | What It Does | |---|---| | Retry with backoff | Both HTTP clients automatically retry on 429 rate limits, 5xx server errors, and transient network failures (ECONNRESET, ETIMEDOUT). 3 retries with exponential backoff. Respects Retry-After headers. | | Clear error messages | Timeouts show "Request timeout (30s): GET /path" instead of cryptic abort errors. API errors include status code, method, path, and response body. | | Zod-validated responses | Critical API paths (contacts, pipelines, calendars, workflows) validate response structure at runtime with Zod schemas. Malformed responses throw immediately with clear errors instead of silently passing garbage. | | Zod-validated config | Token registry (.ghl-tokens.json) and template files are validated against Zod schemas on load. Corrupted files are backed up and reported, not silently accepted. | | Pre-flight workflow validation | validateActionChain() checks action attributes before sending to GHL — catches missing body on SMS, missing subject/html on email, missing pipelineId/stageId on create_opportunity, and more. Prevents GHL's silent failure mode where bad actions kill all subsequent steps. | | Delete confirmation | 10 high-risk destructive operations (delete_contact, delete_workflow, delete_pipeline, delete_funnel, etc.) require confirm: "DELETE" parameter. Prevents accidental deletion. | | Thread-safe token refresh | Firebase token refresh uses a promise-based lock — concurrent requests share one refresh instead of racing. Failed refresh clears the cache immediately instead of leaving a stale token for 55 minutes. | | Startup validation | Server validates the API key at startup (non-blocking) and logs a clear warning if it's invalid. | | Type-safe registration | Tool modules are registered via a typed array — the compiler catches missing registrations. | | Honest types | HTTP client methods return Promise<unknown>, not Promise<T>. No as T casts on JSON.parse. The type system never lies about response shapes. |

Updates

Automatic. Every Claude restart, npx -y @elitedcs/ghl-mcp@latest re-resolves the latest published version. When v3.0.1 ships, every buyer is on it next time they reopen Claude. Zero action required.

To pin a specific version (e.g. for stability), change @latest to @3.0.0 in your MCP config.

Contributing

Source repo is private. Contributors need an invitation from drjerryrelth. The npm-published artifact is open; the build/source pipeline is not.

For contributors with repo access:

1. Clone the repo, run npm install
2. For dev work, set env vars in your shell or a wrapper script (env vars take priority over the credentials file — your dev workflow won't conflict with a buyer install on the same machine):

   export GHL_API_KEY=pit-your-dev-key
   export GHL_LOCATION_ID=your-test-location
   node dist/index.js

3. Read CONTRIBUTING.md for branching conventions, how to add tools, and PR guidelines.
4. Create a branch, run npm run build, test against a sandbox sub-account, open a PR against main.

Environment Variables

| Variable | Required | Description | |---|---|---| | GHL_API_KEY | Yes | Your GHL Private Integration API key. Must be created inside the sub-account you're connecting to (not at the agency level). Can only be copied once at creation. | | GHL_LOCATION_ID | No | Default sub-account ID. Must match the sub-account where you created the API key. Saves you from passing it with every tool call. | | GHL_USER_ID | No* | Your GHL user ID. Required for workflow builder tools. | | GHL_FIREBASE_API_KEY | No* | Firebase API key from GHL's auth system. Required for workflow builder tools. | | GHL_FIREBASE_REFRESH_TOKEN | No* | Firebase refresh token. Required for workflow builder tools. May rotate periodically. | | GHL_ENABLED_MODULES | No | Comma-separated module names to limit which tool groups register at startup (e.g. contacts,conversations,locations). Unset = every module registers (default). See "Reducing context / token usage" below. | | GHL_ENABLED_TOOLS | No | Comma-separated individual tool names to register (e.g. search_contacts,get_contact,update_custom_value). Set alongside GHL_ENABLED_MODULES to add specific tools on top of whole-module enables. |

*Required only for the workflow builder (internal API) tools. The standard API tools work without these.

Reducing context / token usage

Every registered MCP tool's schema is shipped to the model on every message. With 219 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with GHL_ENABLED_MODULES and/or GHL_ENABLED_TOOLS:

// Claude Desktop config — enable whole modules
"env": {
  "GHL_API_KEY": "pit-...",
  "GHL_LOCATION_ID": "...",
  "GHL_ENABLED_MODULES": "contacts,conversations,locations,custom-objects"
}

// Or pin to individual tools
"env": {
  "GHL_API_KEY": "pit-...",
  "GHL_LOCATION_ID": "...",
  "GHL_ENABLED_TOOLS": "search_contacts,get_contact,update_custom_value"
}

Rules of the road:

• Neither set → every tool registers (default, backward compatible — your existing config keeps working unchanged).
• GHL_ENABLED_MODULES only → register tools in those modules.
• GHL_ENABLED_TOOLS only → register only those exact tool names.
• Both set → register the union: a tool registers if its module is in GHL_ENABLED_MODULES OR its name is in GHL_ENABLED_TOOLS. (Whole modules plus a few extra tools.)
• Whitespace and commas both work as separators. Matching is case-insensitive.
• Always-on tools register regardless of the allowlist so setup and recovery still work: setup_ghl_mcp, request_license, get_mcp_version, auto_capture_firebase_script, enable_workflow_builder, health_check.
• Unrecognized module/tool names log a one-line WARNING to stderr and are ignored. Startup never aborts.
• On startup with the allowlist active, the server logs one summary line: Tool allowlist active: registered N of M tools (...).

Valid module names (use these in GHL_ENABLED_MODULES):

contacts, conversations, opportunities, calendars, locations, workflows, funnels, forms, surveys, payments, products, invoices, campaigns, users, media, social-planner, courses, businesses, blogs, emails, trigger-links, custom-objects, associations, estimates, coupons, webhooks, documents, bulk-operations, account-export, template-deployer, workflow-builder, funnel-builder, form-builder, pipeline-builder, workflow-cloner, smart-lists, reputation, email-campaigns, email-builder, memberships, validators, diagnostics, location-switcher

Troubleshooting

| Error | Cause | Fix | |---|---|---| | Only setup_ghl_mcp shows up; no other tools | Bootstrap mode — credentials not yet activated | Run setup_ghl_mcp with all four required fields, then restart Claude | | MCP tools don't appear (CLI) | Server not registered | Run claude mcp add --scope user -t stdio ghl -- npx -y @elitedcs/ghl-mcp@latest | | MCP tools don't appear (Desktop App) | Config missing or wrong | Check ~/Library/Application Support/Claude/claude_desktop_config.json has a ghl entry under mcpServers (see Quick Start above for the exact block) | | MCP tools don't appear (Desktop App) | App not restarted | Quit the Claude app completely (Cmd+Q on Mac) and reopen it | | License key not found | Wrong email or license_key | Both must match exactly what we have on file. Check spam for the welcome email. | | License key already activated on 3 devices | Activation limit hit | Email [email protected] to reset | | locationId is required | Tool needs a location ID | Set GHL_LOCATION_ID in your env, or tell Claude which location to use | | GHL API Error 401 | Invalid or expired key | Generate a new API key in GHL > Settings > Integrations | | GHL API Error 403 | Key from wrong sub-account | Create a new Private Integration inside the correct sub-account | | GHL API Error 403 (alt) | Missing permission scope | Edit your Private Integration in GHL and enable the required scope | | GHL API Error 422 | Invalid request data | Check the error message for which field is wrong | | GHL API Error 429 | Rate limited | Wait a moment and retry |

About

Built by Elite DCs, LLC — a digital marketing and automation agency specializing in GoHighLevel implementations for healthcare practices and local businesses.

Tech stack: TypeScript, Node.js, esbuild, MCP SDK, Zod, GHL API v2, Firebase Auth

Version: 3.34.0

License

MIT License — see LICENSE for full text.

Copyright (c) 2026 Elite DCs, LLC. All rights reserved.