ghl-master

GHL Master by Sales Factory Agency — GoHighLevel MCP Server

Full GoHighLevel API access for Claude. 620+ tools across 40+ modules — manage contacts, conversations, pipelines, calendars, funnels, workflows, invoices, custom objects, webhooks, and more. Includes the programmatic workflow builder (with ready-made recipes + auto-verify), landing-page editing, Conversation AI & Voice AI agents, Knowledge Base, SaaS/rebilling, Store, Proposals, form & pipeline builders, 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. Private by design: it runs locally — your access token and CRM data never pass through a third-party server.

Distributed via npm as ghl-master. 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. Buy at ghl.salesfactoryagency.com/buy — one-time $97, three-machine activation, no subscription.

Built by GHL Master by Sales Factory Agency.

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

ghl.salesfactoryagency.com/buy — one-time $97. 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", "ghl-master@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 ghl-master@latest

Then restart Claude Code.

3. Activate

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

Run setup_ghl_mcp to activate GHL Master by Sales Factory Agency:
  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 — all core tools are now unlocked (620+ 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: ghl.salesfactoryagency.com/firebase-guide

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.

• Log into GoHighLevel
• Switch into the specific sub-account you want to connect (not the agency view)
• Go to Settings > Integrations
• Click Private Integrations > Create Private Integration
• Name it Claude Code MCP
• Enable all scopes/permissions you want Claude to access
• 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 rest of the 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:

• Open app.gohighlevel.com in Chrome (or any Chromium browser), log in.
• Open DevTools (Cmd+Opt+I on Mac, F12 on Windows) → Application tab → IndexedDB in the left panel.
• Expand: firebaseLocalStorageDb → firebaseLocalStorage.
• Find the row whose key starts with firebase:authUser:.
• The part between authUser: and :[DEFAULT] is your ghl_firebase_api_key (starts with AIza).
• Inside that row's value object: uid is your ghl_user_id.
• 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:

• 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.

• 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).

• Register the client's company Firebase:

  register_company_firebase
    companyId: CLIENT_COMPANY_ID         (shown in register_location's output)
    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)
  

• 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.

Tools (190)

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 (~212KB)
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                   # ghl-master
├── 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/ghl-master/credentials.json on Mac) at chmod 0600. Never in code, never committed.
License validation	One-time check at setup_ghl_mcp against ghl.salesfactoryagency.com license server. After activation, no further phone-home.
Multi-user	Each user brings their own license key + GHL API key. Complete account isolation.
Scope	The server only talks to GHL's API and (once, at setup) the ghl.salesfactoryagency.com license server. No filesystem access beyond the credentials file, 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 ghl-master@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 the vendor. The npm-published artifact is open; the build/source pipeline is not.

For contributors with repo access:

• Clone the repo, run npm install
• 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
  

• Read CONTRIBUTING.md for branching conventions, how to add tools, and PR guidelines.
• 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.

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

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 ghl-master@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 [e-mail] 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 GHL Master by Sales Factory Agency — 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: 2.3.0

License

MIT License — see LICENSE for full text.

Copyright (c) 2026 GHL Master by Sales Factory Agency. All rights reserved.