io.github.northrosetech/ghl-mcp-server
GoHighLevel CRM for AI agents. 60+ tools for contacts, messaging, calendars, and payments.
Open source Open in the app JSON README (API)
About
GoHighLevel CRM for AI agents. 60+ tools for contacts, messaging, calendars, and payments.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- northrosetech
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 1
- Last push
- 2026-04-23T06:56:19Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:55
- Updated
- 2026-08-29 04:00:55
- Origin id
io.github.northrosetech/ghl-mcp-server
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)