GoHighLevel MCP Server

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

---

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

---

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)

1. Log in to GoHighLevel and navigate to your sub-account (not the agency dashboard)
2. Go to Settings → Private Integrations
3. Click + Create New Integration
4. Give it a name (e.g. AI Agent) and select all the scopes you want to grant
5. 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

1. Open Cursor Settings → MCP (or press Cmd+Shift+P → "Open MCP Settings")
2. 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"
  }
}

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

Social & Media

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

1. Find the relevant module in src/tools/
2. 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);
       }
     },
   }
   

3. Run npm run typecheck to verify no type errors
4. 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:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/my-new-tool)
3. Make your changes and run npm run typecheck
4. 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_.

---

License

MIT © Business AI Specialist

---

Related

• GoHighLevel API v2 Documentation
• Model Context Protocol
• MCP TypeScript SDK