# ghl-mcp-server [Health: Active]

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/northrosetech/ghl-mcp-server  
**GitHub Stars:** 1  
**npm Downloads (last month):** 125  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ghl-mcp-server

## Description
GoHighLevel CRM for AI agents. 60+ tools for contacts, messaging, calendars, and payments.

## Tools
Capabilities this server exposes over MCP:

- **ghl_search_contacts** — Search contacts in GoHighLevel by query, tags, filters, or custom fields. Returns paginated results.

Args:
  - query (string): Search term (name, email, phone)
  - locationId (string): Location ID (uses default if omitted)
  - limit (number): Results per page (1-100, default 20)
  - filters (object): Advanced filters like tags, date ranges, custom fields

Returns: List of contacts with pagination metadata.
- **ghl_get_contact** — Get a single contact by ID with all details including custom fields, tags, and activity.
- **ghl_create_contact** — Create a new contact in GoHighLevel.

Args:
  - firstName, lastName, email, phone (strings): Basic contact info
  - tags (string[]): Tags to apply
  - source (string): Lead source
  - customFields (array): Custom field values as [{id, field_value}]
  - locationId (string): Location ID (uses default if omitted)

Returns: Created contact object with ID.
- **ghl_update_contact** — Update an existing contact. Only pass fields you want to change.
- **ghl_delete_contact** — Permanently delete a contact. This cannot be undone.
- **ghl_upsert_contact** — Create or update a contact by email/phone. If a match is found, updates; otherwise creates new.
- **ghl_add_contact_tags** — Add one or more tags to a contact.
- **ghl_remove_contact_tags** — Remove one or more tags from a contact.
- **ghl_get_contact_notes** — Get all notes for a contact.
- **ghl_create_contact_note** — Add a note to a contact.
- **ghl_delete_contact_note** — Delete a specific note from a contact.
- **ghl_get_contact_tasks** — Get all tasks for a contact.
- **ghl_create_contact_task** — Create a task for a contact.
- **ghl_update_contact_task** — Update an existing task for a contact.
- **ghl_add_contact_to_workflow** — Add a contact to a GHL workflow/automation.
- **ghl_remove_contact_from_workflow** — Remove a contact from a GHL workflow.
- **ghl_search_conversations** — Search conversations by contact ID, query, or status. Returns threaded conversations with latest message info.
- **ghl_get_conversation** — Get a single conversation by ID with metadata.
- **ghl_get_messages** — Get messages in a conversation thread. Returns SMS, email, and other message types.
- **ghl_send_message** — Send a message (SMS, Email, WhatsApp, or other) to a contact via GoHighLevel.

Args:
  - type: "SMS", "Email", "WhatsApp", "GMB", "IG", "FB", "Custom", "Live_Chat"
  - contactId: The recipient contact ID
  - message: The message body (text for SMS/WhatsApp, HTML for email)
  - subject: Email subject (required for Email type)
  - emailFrom: Sender email (for Email type)
  - html: HTML body (for Email type, alternative to message)
  - scheduledTimestamp: ISO timestamp to schedule future send

Returns: Sent message object with ID and status.
- **ghl_cancel_scheduled_message** — Cancel a previously scheduled message.
- **ghl_update_conversation** — Update conversation status (starred, unread, etc.).
- **ghl_list_calendars** — Get all calendars for the location.
- **ghl_get_calendar** — Get details of a specific calendar.
- **ghl_get_free_slots** — Get available booking slots for a calendar within a date range.
- **ghl_get_events** — Get appointments/events for a location, optionally filtered by calendar, contact, or date range.
- **ghl_create_event** — Create a new appointment/event on a GHL calendar.
- **ghl_update_event** — Update an existing appointment/event.
- **ghl_delete_event** — Delete/cancel an appointment.
- **ghl_create_calendar** — Create a new calendar in GoHighLevel.
- **ghl_search_opportunities** — Search opportunities (deals) by pipeline, stage, status, contact, or monetary value.
- **ghl_get_opportunity** — Get details of a specific opportunity/deal.
- **ghl_create_opportunity** — Create a new opportunity/deal in a pipeline.
- **ghl_update_opportunity** — Update an existing opportunity — move stages, change value, update status, etc.
- **ghl_delete_opportunity** — Permanently delete an opportunity.
- **ghl_update_opportunity_status** — Change the status of an opportunity (open, won, lost, abandoned).
- **ghl_list_pipelines** — Get all pipelines and their stages for a location.
- **ghl_list_orders** — Get payment orders for a location.
- **ghl_get_order** — Get details of a specific payment order.
- **ghl_list_transactions** — Get payment transactions for a location.
- **ghl_list_subscriptions** — Get active subscriptions for a location.
- **ghl_list_invoices** — Get invoices for a location. Filter by status, contact, or date range.
- **ghl_get_invoice** — Get details of a specific invoice.
- **ghl_create_invoice** — Create a new invoice for a contact.
- **ghl_send_invoice** — Send an invoice to the contact via email.
- **ghl_void_invoice** — Void an existing invoice.
- **ghl_list_workflows** — Get all workflows/automations for a location.
- **ghl_list_custom_fields** — Get all custom fields for contacts in a location.
- **ghl_create_custom_field** — Create a new custom field for contacts.
- **ghl_get_location** — Get details of a GHL location/sub-account including settings, address, and configuration.
- **ghl_get_location_tags** — Get all tags defined in a location.
- **ghl_create_location_tag** — Create a new tag in the location.
- **ghl_search_users** — Search for users/team members in a location.
- **ghl_list_forms** — Get all forms for a location.
- **ghl_get_form_submissions** — Get submissions for forms in a location.
- **ghl_list_surveys** — Get all surveys for a location.
- **ghl_list_campaigns** — Get all campaigns for a location.
- **ghl_list_social_posts** — Get scheduled and published social media posts.
- **ghl_create_social_post** — Schedule or publish a social media post.
- **ghl_list_social_accounts** — Get all connected social media accounts (Facebook, Instagram, Google, etc.).
- **ghl_list_funnels** — Get all funnels/websites for a location.
- **ghl_list_products** — Get all products for a location.
- **ghl_list_blogs** — Get all blogs for a location.
- **ghl_list_links** — Get all trigger links for a location.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ghl-mcp-server": {
    "command": "npx",
    "args": ["-y","@northrosetech/ghl-mcp-server"]
  }
}
```

## Documentation & README

# GHL MCP Server

> GoHighLevel MCP Server for Claude, N8N, and Custom AI Agents
> Built by Saurabh K Shah (https://saurabhshah.com)

A comprehensive Model Context Protocol (MCP) server that connects AI assistants directly to your GoHighLevel CRM. Supports **60+ tools** across contacts, conversations, calendars, pipelines, payments, invoices, workflows, custom fields, social media, and more.

## Features

- **Contacts**: Search, create, update, delete, upsert, tags, notes, tasks, workflow management
- **Conversations & Messaging**: SMS, Email, WhatsApp, search threads, send messages, schedule sends
- **Calendars & Appointments**: List calendars, get free slots, create/update/delete events
- **Opportunities & Pipelines**: Full deal management, stage transitions, pipeline listing
- **Payments & Invoices**: Orders, transactions, subscriptions, create/send/void invoices
- **Workflows**: List all workflows, add/remove contacts from workflows
- **Custom Fields**: List, create custom fields for contacts
- **Locations**: Sub-account details, tags management
- **Users**: Search team members
- **Forms & Surveys**: List forms/surveys, get submissions
- **Campaigns**: List all campaigns
- **Social Media**: List/create posts, view connected accounts
- **Funnels & Blogs**: List funnels, blogs
- **Products**: List products and prices

## Quick Start

### 1. Get Your GHL Credentials

1. Log into GoHighLevel → **Settings** → **Private Integrations**
2. Click **Create New Integration**
3. Name it (e.g., "Claude MCP Server")
4. Select all scopes you need (contacts, conversations, calendars, payments, etc.)
5. Copy the **Private Integration Token**
6. Note your **Location ID** (visible in the URL when viewing any sub-account)

### 2. Install & Configure

```bash
git clone https://github.com/northrosetech/ghl-mcp-server.git
cd ghl-mcp-server
npm install
cp .env.example .env
```

Edit `.env`:
```env
GHL_API_KEY=your_private_integration_token_here
GHL_LOCATION_ID=your_location_id_here
```

Build:
```bash
npm run build
```

### 3. Connect to Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "your_private_integration_token",
        "GHL_LOCATION_ID": "your_location_id",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

Restart Claude Desktop. You should see GHL tools available.

### 4. Connect to N8N (HTTP Mode)

Start the server in HTTP mode:
```bash
TRANSPORT=http PORT=3001 GHL_API_KEY=your_token GHL_LOCATION_ID=your_id node dist/index.js
```

In N8N:
1. Add an **MCP Client** node
2. Set URL to `http://localhost:3001/mcp`
3. Set transport to **HTTP Streamable**
4. Use the GHL tools in your workflows

### 5. Connect to Claude Code

Add to your project's `.mcp.json`:
```json
{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["./ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "your_token",
        "GHL_LOCATION_ID": "your_id"
      }
    }
  }
}
```

## Available Tools (60+)

### Contacts (15 tools)
| Tool | Description |
|------|-------------|
| `ghl_search_contacts` | Search contacts by query, tags, filters |
| `ghl_get_contact` | Get contact by ID |
| `ghl_create_contact` | Create new contact |
| `ghl_update_contact` | Update existing contact |
| `ghl_delete_contact` | Delete contact |
| `ghl_upsert_contact` | Create or update by email/phone |
| `ghl_add_contact_tags` | Add tags to contact |
| `ghl_remove_contact_tags` | Remove tags from contact |
| `ghl_get_contact_notes` | Get contact notes |
| `ghl_create_contact_note` | Add note to contact |
| `ghl_delete_contact_note` | Delete a note |
| `ghl_get_contact_tasks` | Get contact tasks |
| `ghl_create_contact_task` | Create task for contact |
| `ghl_update_contact_task` | Update task |
| `ghl_add_contact_to_workflow` | Add contact to workflow |
| `ghl_remove_contact_from_workflow` | Remove from workflow |

### Conversations & Messaging (6 tools)
| Tool | Description |
|------|-------------|
| `ghl_search_conversations` | Search conversation threads |
| `ghl_get_conversation` | Get conversation details |
| `ghl_get_messages` | Get messages in a thread |
| `ghl_send_message` | Send SMS/Email/WhatsApp/etc. |
| `ghl_cancel_scheduled_message` | Cancel scheduled message |
| `ghl_update_conversation` | Update conversation status |

### Calendars & Appointments (8 tools)
| Tool | Description |
|------|-------------|
| `ghl_list_calendars` | List all calendars |
| `ghl_get_calendar` | Get calendar details |
| `ghl_get_free_slots` | Get available booking slots |
| `ghl_get_events` | Get appointments/events |
| `ghl_create_event` | Create appointment |
| `ghl_update_event` | Update appointment |
| `ghl_delete_event` | Delete appointment |
| `ghl_create_calendar` | Create new calendar |

### Opportunities & Pipelines (7 tools)
| Tool | Description |
|------|-------------|
| `ghl_search_opportunities` | Search deals |
| `ghl_get_opportunity` | Get deal details |
| `ghl_create_opportunity` | Create new deal |
| `ghl_update_opportunity` | Update deal / move stages |
| `ghl_delete_opportunity` | Delete deal |
| `ghl_update_opportunity_status` | Change deal status |
| `ghl_list_pipelines` | List pipelines & stages |

### Payments & Invoices (9 tools)
| Tool | Description |
|------|-------------|
| `ghl_list_orders` | List payment orders |
| `ghl_get_order` | Get order details |
| `ghl_list_transactions` | List transactions |
| `ghl_list_subscriptions` | List subscriptions |
| `ghl_list_invoices` | List invoices |
| `ghl_get_invoice` | Get invoice details |
| `ghl_create_invoice` | Create invoice |
| `ghl_send_invoice` | Email invoice to contact |
| `ghl_void_invoice` | Void an invoice |

### Other Tools (15+ tools)
| Tool | Description |
|------|-------------|
| `ghl_list_workflows` | List all workflows |
| `ghl_list_custom_fields` | List custom fields |
| `ghl_create_custom_field` | Create custom field |
| `ghl_get_location` | Get location details |
| `ghl_get_location_tags` | Get location tags |
| `ghl_create_location_tag` | Create new tag |
| `ghl_search_users` | Search team members |
| `ghl_list_forms` | List forms |
| `ghl_get_form_submissions` | Get form submissions |
| `ghl_list_surveys` | List surveys |
| `ghl_list_campaigns` | List campaigns |
| `ghl_list_social_posts` | List social posts |
| `ghl_create_social_post` | Create/schedule social post |
| `ghl_list_social_accounts` | List connected social accounts |
| `ghl_list_funnels` | List funnels/websites |
| `ghl_list_products` | List products |
| `ghl_list_blogs` | List blogs |
| `ghl_list_links` | List trigger links |

## Architecture

```
ghl-mcp-server/
├── src/
│   ├── index.ts              # Entry point (stdio + HTTP transport)
│   ├── constants.ts          # All GHL API endpoints & config
│   ├── types.ts              # TypeScript interfaces
│   ├── services/
│   │   └── api-client.ts     # Auth, rate limiting, error handling
│   └── tools/
│       ├── contacts.ts       # Contact management tools
│       ├── conversations.ts  # Messaging tools
│       ├── calendars.ts      # Calendar & appointment tools
│       ├── opportunities.ts  # Pipeline & deal tools
│       └── business.ts       # Payments, invoices, workflows, etc.
├── dist/                     # Compiled JS
├── package.json
├── tsconfig.json
└── .env.example
```

## Rate Limits

The server includes built-in rate limiting matching GHL's limits:
- **Burst**: 100 requests per 10 seconds
- **Daily**: 200,000 requests per day

The server automatically queues and retries when limits are approached.

## Error Handling

All tools return actionable error messages with hints:
- **401**: Check your API key (must be Private Integration Token)
- **403**: Missing scopes — edit your Private Integration in GHL Settings
- **404**: Resource not found — check the ID
- **422**: Validation error with details
- **429**: Rate limit — automatic retry

## License

MIT — Built by Saurabh K Shah (https://saurabhshah.com)