# GHL MCP Server

A remote MCP (Model Context Protocol) server running on Cloudflare Workers that gives AI agents full programmatic access to GoHighLevel.

## What This Does

Your AI agents connect to this server as a tool. They can then create, read, update, and delete custom fields, custom values, and custom field folders in your GHL account — no manual work required.

**Current capabilities (Phase 1):**
- Contact-level custom fields (full CRUD + bulk create)
- Custom object fields (Custom Objects + Company)
- Custom field folders
- Custom values (location-wide variables)

**Planned (Phase 2+):**
- Contacts management
- Opportunities & Pipelines
- Calendars & Appointments
- Conversations & Messaging
- Workflows
- And every other GHL API endpoint

## Architecture

```
Your AI Agent (Claude, GPT, etc.)
        │
        │  MCP Protocol (Streamable HTTP)
        ▼
┌─────────────────────────┐
│  Cloudflare Worker       │
│  (GHL MCP Server)        │
│                          │
│  ┌────────────────────┐  │
│  │  McpAgent          │  │  ← Durable Object (stateful sessions)
│  │  (tools defined)   │  │
│  └────────┬───────────┘  │
│           │              │
│  ┌────────▼───────────┐  │
│  │  GHL API Client    │  │  ← Typed HTTP client
│  └────────┬───────────┘  │
└───────────┼──────────────┘
            │
            │  REST API (Bearer token)
            ▼
┌─────────────────────────┐
│  GoHighLevel API         │
│  services.leadconnector  │
│  hq.com                  │
└─────────────────────────┘
```

## Setup

### Prerequisites

- Node.js 18+
- A Cloudflare account
- A GoHighLevel Private Integration Token
- Your GHL Location ID (Sub-Account ID)

### 1. Clone & Install

```bash
git clone https://github.com/YOUR_USERNAME/ghl-mcp-server.git
cd ghl-mcp-server
npm install
```

### 2. Configure Secrets

For local development, copy the example env file:
```bash
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your actual GHL credentials
```

For production deployment, set secrets via Wrangler:
```bash
npx wrangler secret put GHL_API_KEY
npx wrangler secret put GHL_LOCATION_ID
```

### 3. Deploy

```bash
npm run deploy
```

Your MCP server will be live at: `https://ghl-mcp-server.YOUR_SUBDOMAIN.workers.dev/sse`

### 4. Connect Your AI Agent

Use the deployed URL as an MCP server endpoint in your AI agent's configuration.

For Claude Desktop (via mcp-remote proxy):
```json
{
  "mcpServers": {
    "ghl": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://ghl-mcp-server.YOUR_SUBDOMAIN.workers.dev/sse"
      ]
    }
  }
}
```

## Available Tools

### Contact-Level Custom Fields
| Tool | Description |
|------|-------------|
| `ghl_list_contact_custom_fields` | List all contact custom fields |
| `ghl_get_contact_custom_field` | Get a specific field by ID |
| `ghl_create_contact_custom_field` | Create a single field |
| `ghl_update_contact_custom_field` | Update a field |
| `ghl_delete_contact_custom_field` | Delete a field |
| `ghl_bulk_create_contact_custom_fields` | Create multiple fields at once |

### Custom Object Fields
| Tool | Description |
|------|-------------|
| `ghl_list_object_custom_fields` | List fields for a custom object |
| `ghl_create_object_custom_field` | Create a field on a custom object |
| `ghl_create_custom_field_folder` | Create a folder for organizing fields |

### Custom Values
| Tool | Description |
|------|-------------|
| `ghl_list_custom_values` | List all custom values |
| `ghl_create_custom_value` | Create a custom value |
| `ghl_update_custom_value` | Update a custom value |
| `ghl_delete_custom_value` | Delete a custom value |

## Supported Field Types

| Type | Description |
|------|-------------|
| `TEXT` | Single-line text |
| `LARGE_TEXT` | Multi-line text |
| `NUMERICAL` | Number |
| `PHONE` | Phone number |
| `MONETORY` | Currency/money |
| `EMAIL` | Email address |
| `DATE` | Date picker |
| `CHECKBOX` | Checkbox |
| `SINGLE_OPTIONS` | Dropdown (single select) |
| `MULTIPLE_OPTIONS` | Multi-select |
| `RADIO` | Radio buttons |
| `FILE_UPLOAD` | File attachment |
| `TEXTBOX_LIST` | List of text inputs |

## Roadmap

### Phase 2: Contacts
- Create, update, delete, search contacts
- Bulk contact operations
- Tag management
- Notes and tasks

### Phase 3: Opportunities & Pipelines
- Pipeline management
- Opportunity CRUD
- Stage updates

### Phase 4: Calendars & Conversations
- Calendar management
- Appointment scheduling
- Send messages (SMS, email)

### Phase 5: Workflows & Automation
- Trigger workflows
- Manage workflow configurations

### Phase 6: Everything Else
- Forms, Surveys, Funnels
- Payments, Invoices, Products
- Media library
- Social media posting

## Development

```bash
# Local development
npm run dev

# Deploy to production
npm run deploy
```

## GHL API Reference

This server is built against the [GoHighLevel API V2](https://marketplace.gohighlevel.com/docs/). The OpenAPI specs from the [official docs repo](https://github.com/GoHighLevel/highlevel-api-docs) are included in `/api-specs` for reference.

## License

MIT