# GoHighLevel MCP Server

A Model Context Protocol (MCP) server that provides tools for managing GoHighLevel (GHL) conversations, tasks, and calendar appointments through AI assistants like Claude.

## Features

### Conversations
- **search_conversations** - Search and filter conversations with various criteria
- **get_conversation** - Get details of a specific conversation
- **create_conversation** - Create a new conversation with a contact
- **update_conversation** - Update conversation (star, assign, mark as read)
- **delete_conversation** - Delete a conversation
- **get_messages** - Get messages in a conversation
- **send_message** - Send SMS, Email, WhatsApp, or other message types

### Tasks
- **get_tasks** - Get all tasks for a contact
- **get_task** - Get a specific task
- **create_task** - Create a new task
- **update_task** - Update an existing task
- **delete_task** - Delete a task
- **complete_task** - Mark a task as completed/incomplete

### Calendar & Appointments
- **get_calendars** - Get all calendars in the location
- **get_calendar** - Get details of a specific calendar
- **get_free_slots** - Get available time slots
- **get_calendar_events** - Get events within a date range
- **get_appointment** - Get appointment details
- **create_appointment** - Create a new appointment
- **update_appointment** - Update an appointment
- **delete_appointment** - Delete an appointment

## Prerequisites

- Node.js 18 or higher
- A GoHighLevel account with API access
- A Private Integration Token (PIT) from GoHighLevel

## Getting Your GHL Credentials

1. Log into your GoHighLevel sub-account
2. Go to **Settings > Integrations > Private Integrations**
3. Click **Create New Integration**
4. Select the required scopes:
   - Contacts: Read, Write
   - Conversations: Read, Write
   - Conversation Messages: Read, Write
   - Calendars: Read, Write
   - Calendar Events: Read, Write
5. Copy the generated Private Integration Token
6. Note your Location ID (found in Settings > Business Profile or in the URL)

## Installation

```bash
# Clone or download this repository
cd ghl-mcp-server

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

### Environment Variables

Set the following environment variables:

```bash
export GHL_API_KEY="pit-your-private-integration-token"
export GHL_LOCATION_ID="your-location-id"
```

### Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-your-private-integration-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}
```

### Cursor IDE Configuration

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "ghl": {
      "command": "node",
      "args": ["/absolute/path/to/ghl-mcp-server/dist/index.js"],
      "env": {
        "GHL_API_KEY": "pit-your-private-integration-token",
        "GHL_LOCATION_ID": "your-location-id"
      }
    }
  }
}
```

## Usage Examples

Once configured, you can use natural language to interact with your GHL account:

### Conversations
- "Search for all unread conversations"
- "Get messages from conversation ID xyz123"
- "Send an SMS to contact abc456 saying 'Thank you for your inquiry!'"
- "Send an email to contact abc456 with subject 'Follow Up' and body 'Hi, just following up...'"

### Tasks
- "Show me all tasks for contact xyz123"
- "Create a task for contact abc456: Call back tomorrow at 2pm"
- "Mark task xyz as completed"
- "Update task abc to change the due date to next Monday"

### Calendar
- "List all calendars"
- "Show me appointments for the next 7 days"
- "Get free slots for calendar xyz between Jan 15 and Jan 20"
- "Create an appointment for contact abc456 on January 15th at 10am"
- "Cancel appointment xyz123"

## API Reference

### Conversation Tools

#### search_conversations
Search conversations with filters like contactId, assignedTo, query text, status, and message direction.

#### send_message
Send messages with support for:
- **SMS**: Simple text messages
- **Email**: With subject, HTML body, CC/BCC, attachments
- **WhatsApp**: WhatsApp messages
- **IG/FB**: Instagram and Facebook messages
- **Live_Chat**: Live chat messages

### Task Tools

#### create_task
Create tasks with:
- Title (required)
- Description/body
- Due date (ISO 8601 format)
- Assignment to specific user
- Completion status

### Calendar Tools

#### create_appointment
Create appointments with:
- Calendar ID (required)
- Contact ID (required)
- Start/end time (ISO 8601 format)
- Title and description
- Meeting location (Zoom, Google Meet, custom, etc.)
- Appointment status
- Notifications/automations toggle

## Development

```bash
# Run in development mode
npm run dev

# Build only
npm run build

# Start production server
npm start
```

## Troubleshooting

### Common Issues

1. **"GHL_API_KEY and GHL_LOCATION_ID environment variables are required"**
   - Ensure both environment variables are set correctly

2. **"401 Unauthorized" errors**
   - Verify your Private Integration Token is valid
   - Check that the token has the required scopes

3. **"400 Bad Request" errors**
   - Verify the request parameters match the API requirements
   - Check that IDs (contact, calendar, etc.) are valid

4. **Server not appearing in Claude Desktop**
   - Verify the path to the server is correct
   - Check the Claude Desktop logs for errors
   - Restart Claude Desktop after configuration changes

## Required Scopes

For full functionality, your Private Integration Token needs these scopes:

- `contacts.readonly` - Read contact information
- `contacts.write` - Create and update tasks
- `conversations.readonly` - Read conversations
- `conversations.write` - Create/update conversations
- `conversations/message.readonly` - Read messages
- `conversations/message.write` - Send messages
- `calendars.readonly` - Read calendars
- `calendars.write` - Manage calendars
- `calendars/events.readonly` - Read events
- `calendars/events.write` - Create/update appointments

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.