Which integrations are available for this server?

Enables sending WhatsApp messages to contacts in GoHighLevel.

GoHighLevel MCP Server

Give any AI agent — Claude, Cursor, Windsurf, or any MCP-compatible client — full access to your GoHighLevel account through natural language.

npm version npm downloads MIT License Node.js MCP GoHighLevel

What is this?

This is a Model Context Protocol (MCP) server that connects your AI tools directly to your GoHighLevel (GHL) sub-account via the GHL API v2.

Once installed, you can talk to your CRM naturally:

"Find all contacts tagged 'cold-lead' and send them an SMS saying we have a new offer" "Book an appointment for Sarah Johnson tomorrow at 2pm on the Discovery calendar" "Move any open opportunities in Stage 1 that haven't been touched in 14 days to 'Lost'" "Create a note on John's contact record and enroll him in the cold call workflow"

127 tools covering the full GHL API:

Category	Tools
Contacts	CRUD, search, upsert, tags, notes, tasks, workflow enrollment, appointments
Conversations & Messaging	Search, send SMS/email/WhatsApp, schedule, message history
Calendars & Appointments	List calendars, check availability, book, reschedule, block slots
Opportunities / Pipeline	Pipelines, deals, stage moves, won/lost/abandoned
Workflows & Campaigns	List workflows and campaigns
Location Settings	Custom fields, custom values, tags, users, templates, forms, surveys
Email Marketing	Email builder templates, email campaigns
Funnels	List funnels, pages, page counts
Phone Numbers	List, search, purchase, update, release phone numbers
Payments & Invoices	Orders, transactions, subscriptions, coupons, invoices, payments
Social & Media	Social posts, media library, trigger links
Knowledge Base, FAQs & Crawler	Create/manage knowledge bases, FAQ pairs, and AI-train websites via crawler

Related MCP server: ghl-mcp

Prerequisites

Before you begin, make sure you have:

Node.js 18 or later — download here
A GoHighLevel account with sub-account access
A GHL Private Integration Token (takes ~2 minutes to create — see below)

How to get your GHL credentials

1. Private Integration Token (GHL_PIT_TOKEN)

Log in to GoHighLevel and navigate to your sub-account (not the agency dashboard)
Go to Settings → Private Integrations
Click + Create New Integration
Give it a name (e.g. AI Agent) and select all the scopes you want to grant
Click Create — copy the token that appears (you won't see it again)

⚠️ Keep this token secret. It grants full API access to your sub-account.

2. Location ID (GHL_LOCATION)

Your Location ID is in the URL when you're inside your sub-account:

https://app.gohighlevel.com/location/XXXXXXXXXXXXXXXXXX/dashboard
                                     ^^^^^^^^^^^^^^^^^^
                                     This is your Location ID

Installation

No build step needed. Pass your credentials directly in your AI client config and the server runs on demand.

Quick install via package manager (recommended)

Use npx, pnpm dlx, or bunx to run the server without installing anything globally:

# npm / npx  (no install required)
npx @nerdsnipe-inc/ghl-mcp-server

# pnpm
pnpm dlx @nerdsnipe-inc/ghl-mcp-server

# bun
bunx @nerdsnipe-inc/ghl-mcp-server

Or install it globally if you prefer:

npm install -g @nerdsnipe-inc/ghl-mcp-server
# then run:
ghl-mcp-server

Connect to your AI tool

Pick your AI client below and follow the instructions.

Connecting to AI Clients

Claude Desktop

Open (or create) your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/ghl-mcp-server"],
      "env": {
        "GHL_PIT_TOKEN": "your_token_here",
        "GHL_LOCATION": "your_location_id_here"
      }
    }
  }
}

Restart Claude Desktop. You should see a hammer icon (🔨) in the chat input — that means MCP tools are active.

Claude Code (CLI)

Run this from your terminal to add the server to your Claude Code config:

claude mcp add ghl npx -- -y @nerdsnipe-inc/ghl-mcp-server \
  -e GHL_PIT_TOKEN=your_token_here \
  -e GHL_LOCATION=your_location_id_here

Or add it manually to ~/.claude/mcp_servers.json (or your project's .mcp.json):

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/ghl-mcp-server"],
      "env": {
        "GHL_PIT_TOKEN": "your_token_here",
        "GHL_LOCATION": "your_location_id_here"
      }
    }
  }
}

Project-scoped tip: Add a .mcp.json in your project root so everyone on the team picks it up automatically — no local install required. Add .mcp.json to .gitignore so tokens aren't committed. If you store credentials in a .env file you can omit the env block entirely.

Cursor

Open Cursor Settings → MCP (or press Cmd+Shift+P → "Open MCP Settings")
Click Add Server and fill in:

{
  "name": "ghl",
  "command": "npx",
  "args": ["-y", "@nerdsnipe-inc/ghl-mcp-server"],
  "env": {
    "GHL_PIT_TOKEN": "your_token_here",
    "GHL_LOCATION": "your_location_id_here"
  }
}

Save and restart Cursor.

Windsurf

Open ~/.codeium/windsurf/mcp_config.json and add:

{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": ["-y", "@nerdsnipe-inc/ghl-mcp-server"],
      "env": {
        "GHL_PIT_TOKEN": "your_token_here",
        "GHL_LOCATION": "your_location_id_here"
      }
    }
  }
}

Any other MCP-compatible client

This server uses stdio transport — the standard for local MCP servers. Your client needs:

Command: npx
Args: ["-y", "@nerdsnipe-inc/ghl-mcp-server"]
Env: GHL_PIT_TOKEN and GHL_LOCATION

Refer to your client's MCP documentation for exact config syntax.

Running from source (contributors)

If you've cloned the repo and want to run directly from TypeScript without a build step:

git clone https://github.com/Nerdsnipe-Inc/ghl-mcp-server.git
cd ghl-mcp-server
npm install

Then point your MCP client at the source via tsx:

{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/ghl-mcp-server/src/index.ts"]
}

Or build first for production use:

npm run build
# then run:
node dist/index.js

All 127 Tools — Full Reference

Contacts

Tool	Description
`ghl_get_contacts`	List/search contacts by name, email, phone, or tags
`ghl_get_contact`	Get a single contact by ID
`ghl_create_contact`	Create a new contact
`ghl_update_contact`	Update contact fields
`ghl_upsert_contact`	Create or update by email/phone (prevents duplicates)
`ghl_delete_contact`	Permanently delete a contact
`ghl_search_contacts`	Advanced search with filter conditions
`ghl_add_contact_tags`	Add tags to a contact
`ghl_remove_contact_tags`	Remove tags from a contact
`ghl_get_contact_notes`	List all notes on a contact
`ghl_create_contact_note`	Add a note to a contact
`ghl_update_contact_note`	Update an existing note
`ghl_delete_contact_note`	Delete a note
`ghl_get_contact_tasks`	List tasks for a contact
`ghl_create_contact_task`	Create a task for a contact
`ghl_update_contact_task`	Update a task (status, due date, etc.)
`ghl_delete_contact_task`	Delete a task
`ghl_add_contact_to_workflow`	Enroll a contact in a workflow/automation
`ghl_remove_contact_from_workflow`	Remove a contact from a workflow
`ghl_get_contact_appointments`	Get all appointments for a contact

Conversations & Messaging

Tool	Description
`ghl_search_conversations`	Search conversations by contact, status, or channel
`ghl_get_conversation`	Get a conversation by ID
`ghl_create_conversation`	Open a new conversation thread
`ghl_get_messages`	List messages in a conversation
`ghl_send_message`	Send SMS, email, WhatsApp, or other channel message
`ghl_send_email`	Send an email within an existing conversation
`ghl_update_message_status`	Mark messages read/unread/delivered
`ghl_cancel_scheduled_message`	Cancel a scheduled (future) message
`ghl_add_inbound_message`	Inject an inbound message (testing/simulation)

Calendars & Appointments

Tool	Description
`ghl_get_calendars`	List all calendars
`ghl_get_calendar`	Get a calendar by ID
`ghl_get_free_slots`	Check available appointment slots in a date range
`ghl_get_calendar_events`	Get events/appointments in a date range
`ghl_create_appointment`	Book an appointment
`ghl_get_appointment`	Get an appointment by event ID
`ghl_update_appointment`	Reschedule, change status, or add notes
`ghl_delete_calendar_event`	Delete an event or appointment
`ghl_create_block_slot`	Block a time period on a calendar
`ghl_get_calendar_groups`	List calendar groups

Opportunities / Pipeline

Tool	Description
`ghl_get_pipelines`	List all pipelines and their stages
`ghl_search_opportunities`	Search deals by contact, stage, pipeline, or status
`ghl_get_opportunity`	Get a single opportunity
`ghl_create_opportunity`	Create a new deal
`ghl_update_opportunity`	Update deal fields (stage, value, assignee)
`ghl_update_opportunity_status`	Quickly mark a deal won/lost/abandoned
`ghl_upsert_opportunity`	Create or update a deal
`ghl_delete_opportunity`	Delete a deal

Workflows & Campaigns

Tool	Description
`ghl_get_workflows`	List all workflows (use to discover workflow IDs)
`ghl_get_campaigns`	List all campaigns

Enrolling contacts in workflows is done via ghl_add_contact_to_workflow.

Email Marketing

Tool	Description
`ghl_get_email_builder_templates`	List all email builder templates in the location
`ghl_get_email_builder_template`	Get a single email builder template by ID
`ghl_create_email_builder_template`	Create a new email builder template with HTML content
`ghl_update_email_builder_template`	Update an existing email builder template's HTML content
`ghl_delete_email_builder_template`	Delete an email builder template by ID
`ghl_get_email_campaigns`	List all email campaigns in the location
`ghl_get_email_campaign`	Get details of a single email campaign by ID
`ghl_create_email_campaign`	Create a new email campaign
`ghl_delete_email_campaign`	Delete an email campaign by ID

Funnels

Tool	Description
`ghl_get_funnels`	List all funnels in the location
`ghl_get_funnel_pages`	List all pages in a specific funnel
`ghl_get_funnel_page_count`	Get the total count of pages in a funnel

Phone Numbers

Tool	Description
`ghl_get_phone_numbers`	List all purchased/active phone numbers in the location
`ghl_search_available_phone_numbers`	Search for available numbers to purchase (filter by area code, country, type)
`ghl_purchase_phone_number`	Purchase a phone number for the location (E.164 format, e.g. `+16135550100`)
`ghl_update_phone_number`	Update settings for a phone number (assignment, call forwarding)
`ghl_release_phone_number`	Release (delete) a phone number from the location

Surveys

Tool	Description
`ghl_get_surveys`	List all surveys created in the location
`ghl_get_survey_submissions`	Get submissions for a survey, with optional filters

Location Settings

Tool	Description
`ghl_get_location`	Get location/sub-account details
`ghl_get_location_tags`	List all tags in the location
`ghl_create_location_tag`	Create a new tag
`ghl_delete_location_tag`	Delete a tag
`ghl_get_custom_fields`	List custom contact fields
`ghl_create_custom_field`	Create a custom field
`ghl_update_custom_field`	Update a custom field
`ghl_delete_custom_field`	Delete a custom field
`ghl_get_custom_values`	List custom values (location-level variables)
`ghl_create_custom_value`	Create a custom value
`ghl_update_custom_value`	Update a custom value
`ghl_delete_custom_value`	Delete a custom value by ID
`ghl_get_users`	List all team members
`ghl_search_users`	Search users by name or email
`ghl_get_user`	Get a single team member by user ID
`ghl_create_user`	Create a new team member in the location
`ghl_update_user`	Update an existing team member
`ghl_delete_user`	Remove a team member from the location
`ghl_get_templates`	List SMS/email/WhatsApp templates
`ghl_create_template`	Create a new SMS/email/WhatsApp template
`ghl_update_template`	Update an existing template
`ghl_delete_template`	Delete a template by ID
`ghl_get_forms`	List all forms
`ghl_get_form_submissions`	Get form submissions

Payments & Invoices

Tool	Description
`ghl_get_orders`	List payment orders
`ghl_get_order`	Get a single order
`ghl_get_transactions`	List payment transactions
`ghl_get_subscriptions`	List active subscriptions
`ghl_get_coupons`	List coupons
`ghl_create_coupon`	Create a discount coupon
`ghl_get_invoices`	List invoices
`ghl_get_invoice`	Get a single invoice
`ghl_create_invoice`	Create a new invoice
`ghl_send_invoice`	Email an invoice to the contact
`ghl_void_invoice`	Void (cancel) an invoice
`ghl_record_invoice_payment`	Record a manual payment on an invoice

Tool	Description
`ghl_get_social_accounts`	List connected social media accounts
`ghl_get_social_posts`	List scheduled or published posts
`ghl_create_social_post`	Schedule or publish a social media post
`ghl_delete_social_post`	Delete a scheduled post
`ghl_get_media_files`	List files in the media library
`ghl_delete_media_file`	Delete a file from the media library
`ghl_get_trigger_links`	List trigger links
`ghl_create_trigger_link`	Create a trigger link
`ghl_delete_trigger_link`	Delete a trigger link

Knowledge Bases

Tool	Description
`ghl_list_knowledge_bases`	List all knowledge bases for the location with cursor-based pagination
`ghl_get_knowledge_base`	Get a single knowledge base by ID — includes metadata counts (FAQs, URLs, files)
`ghl_create_knowledge_base`	Create a new knowledge base (max 15 per location)
`ghl_update_knowledge_base`	Update the name or description of an existing knowledge base
`ghl_delete_knowledge_base`	Permanently delete a knowledge base and all its content (FAQs, trained URLs, etc.)

FAQs

Tool	Description
`ghl_list_faqs`	List all FAQ question/answer pairs for a knowledge base with cursor-based pagination
`ghl_create_faq`	Add a new FAQ question and answer to a knowledge base
`ghl_update_faq`	Update the question and answer text of an existing FAQ
`ghl_delete_faq`	Permanently delete an FAQ by ID

Web Crawler

Use the crawler to discover and ingest website pages as AI training data for a knowledge base. The typical flow is: discover → check status → train.

Tool	Description
`ghl_discover_website`	Start crawling a website to discover pages. Choose scope: `Exact` (one URL), `Path` (sub-paths), or `Domain` (all). Returns an `operationId`
`ghl_get_crawler_status`	Check progress of a crawl job by `operationId` — returns per-URL status (Pending, Successful, Failed, etc.)
`ghl_list_crawler_urls`	List all trained page links for a knowledge base. Use to retrieve `urlIds` for training or deletion
`ghl_train_crawler_urls`	Ingest discovered pages into the knowledge base for AI training using `urlIds` from the crawler
`ghl_delete_crawler_urls`	Remove previously trained page URLs from a knowledge base by `urlIds`

Example Prompts

Here are some things you can say to your AI once connected:

"Find all contacts tagged 'new-lead' added this week and send them a welcome SMS"

"What appointments are booked on the Discovery calendar this Friday?"

"Check Sarah Johnson's conversation history and summarize the last 5 messages"

"Create a note on contact ID abc123 saying 'Called, left voicemail' and mark the task as complete"

"Move all open opportunities in the Onboarding pipeline older than 30 days to 'Lost'"

"Book an appointment for john@example.com tomorrow at 3pm on calendar XYZ"

"Enroll contact ID abc123 in the cold call workflow"

"Show me all unpaid invoices over 30 days old"

"List all users/team members in this location"

"What workflows do we have? Show me the names and IDs"

"Create a knowledge base called 'Product FAQ' and add 5 FAQs covering our pricing, refund policy, and onboarding steps"

"Crawl https://example.com and train our support knowledge base on every page under /docs"

"List all the FAQs in our knowledge base and update any that mention the old pricing"

"Show me the status of the last website crawl and train on all successfully discovered pages"

Environment Variables Reference

Variable	Required	Description
`GHL_PIT_TOKEN`	✅ Yes	Your GHL Private Integration Token
`GHL_LOCATION`	✅ Yes	Your sub-account location ID

That's it — just two variables. Workflow IDs, pipeline IDs, calendar IDs, and all other GHL resource identifiers are passed directly as parameters when you call the relevant tools. This keeps the server generic and usable across any project or use case.

Development

# Install dependencies
npm install

# Run in development mode (no build step needed)
npm run dev

# Type-check without building
npm run typecheck

# Build for production
npm run build

# Watch mode (rebuilds on file changes)
npm run build:watch

Project Structure

ghl-mcp-server/
├── src/
│   ├── index.ts          # MCP server entry point — registers all tools
│   ├── client.ts         # GHL HTTP client (auth, request helper, error handling)
│   └── tools/
│       ├── contacts.ts       # 21 contact tools
│       ├── conversations.ts  #  9 conversation & messaging tools
│       ├── calendars.ts      # 10 calendar & appointment tools
│       ├── opportunities.ts  #  8 pipeline & deal tools
│       ├── workflows.ts      #  2 workflow & campaign tools
│       ├── locations.ts      # 16 location settings tools
│       ├── payments.ts       # 12 payment & invoice tools
│       ├── social.ts         #  8 social, media & trigger link tools
│       ├── emails.ts         #  9 email builder & campaign tools
│       ├── funnels.ts        #  3 funnel tools
│       ├── phone_numbers.ts  #  5 phone number tools
│       ├── surveys.ts        #  2 survey tools
│       └── knowledge_base.ts # 14 knowledge base, FAQ & web crawler tools
├── dist/                 # Compiled output (generated by npm run build)
├── .env.example          # Environment variable template
├── package.json
├── tsconfig.json
└── README.md

Adding a new tool

Find the relevant module in src/tools/

Add a new entry to the exported array following the existing pattern:

{
  name: "ghl_your_tool_name",
  description: "What this tool does and when to use it",
  inputSchema: z.object({
    param: z.string().describe("Description of this parameter"),
  }),
  handler: async (args, config) => {
    try {
      const result = await ghlRequest("GET", "/your/endpoint", {
        token: config.token,
        params: { locationId: config.locationId, ...args },
      });
      return JSON.stringify(result, null, 2);
    } catch (e) {
      return formatError(e);
    }
  },
}

Run npm run typecheck to verify no type errors
Submit a PR!

Troubleshooting

The server isn't showing up in my AI client

Make sure you ran npm run build and the dist/ folder exists
Double-check the absolute path to dist/index.js in your config
Restart your AI client after changing MCP config

Getting "GHL_PIT_TOKEN is not set" errors

Verify your .env file exists in the ghl-mcp-server/ directory
Or pass the env vars directly in your MCP client config (see setup instructions above)

Getting 401 Unauthorized from the API

Your PIT token may have expired or been revoked — generate a new one in GHL Settings → Private Integrations
Make sure the token is for the correct sub-account

Getting 422 or 400 errors

Check the details field in the error response — GHL usually explains what's wrong
Common causes: missing required fields, invalid phone number format (use E.164: +15551234567), invalid date format (use ISO 8601)

Rate limit errors (429)

GHL enforces 100 requests per 10 seconds
For bulk operations, add a small delay between calls or process in batches

Contributing

Pull requests are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/my-new-tool)
Make your changes and run npm run typecheck
Commit and push, then open a PR

When adding new tools, follow the existing patterns in src/tools/ and keep the tool names prefixed with ghl_.