# GoHighLevel MCP Server

An MCP (Model Context Protocol) server that integrates with the [GoHighLevel](https://www.gohighlevel.com/) CRM API. Enables LLMs to read conversations, send messages, create tasks, and manage calendar appointments within GoHighLevel locations.

## Tools

| Tool | Description |
|---|---|
| `ghl_search_conversations` | Search conversations in a location by query, status, contact, or assigned user |
| `ghl_get_conversation` | Get details of a single conversation by ID |
| `ghl_get_messages` | Retrieve messages from a conversation (with pagination) |
| `ghl_send_message` | Send SMS, Email, WhatsApp, Instagram, Facebook, or Live Chat messages |
| `ghl_create_conversation` | Create a new conversation for a contact in a location |
| `ghl_get_tasks` | List all tasks for a contact |
| `ghl_create_task` | Create a new task on a contact |
| `ghl_get_calendars` | List all calendars in a location |
| `ghl_get_calendar_events` | Get appointments/events within a date range |
| `ghl_create_appointment` | Book a new appointment on a calendar |

## Prerequisites

- Python 3.10+
- A GoHighLevel account with API access
- A **Private Integration Token** or **OAuth Access Token** (Sub-Account level)

## Installation

```bash
cd gohighlevel-mcp
pip install -e .
```

## Configuration

Set your GoHighLevel API token as an environment variable:

```bash
export GHL_API_KEY="your-gohighlevel-api-token"
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gohighlevel": {
      "command": "python3",
      "args": ["-m", "gohighlevel_mcp.server"],
      "env": {
        "GHL_API_KEY": "your-gohighlevel-api-token"
      }
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add gohighlevel -- python3 -m gohighlevel_mcp.server
```

Make sure `GHL_API_KEY` is set in your shell environment before running.

## API Scopes Required

The token you provide needs these GoHighLevel API scopes:

| Scope | Used By |
|---|---|
| `conversations.readonly` | Search & get conversations |
| `conversations.write` | Create conversations |
| `conversations/message.readonly` | Read messages |
| `conversations/message.write` | Send messages |
| `contacts.readonly` | List tasks |
| `contacts.write` | Create tasks |
| `calendars.readonly` | List calendars |
| `calendars/events.readonly` | Get calendar events |
| `calendars/events.write` | Create appointments |

## Example Usage

Once connected, you can ask your LLM things like:

- "Show me unread conversations in location `abc123`"
- "Get the last 10 messages from conversation `xyz789`"
- "Send an SMS to contact `def456` saying 'Your appointment is confirmed'"
- "Create a task for contact `ghi012` titled 'Follow up call' due tomorrow"
- "List all calendars in location `abc123`"
- "Book an appointment on calendar `cal001` for contact `def456` tomorrow at 2pm"