# GoHighLevel MCP Server

Conecta [Claude Code](https://claude.ai/claude-code) (o cualquier cliente MCP) directamente con tu CRM de GoHighLevel.

Lee y gestiona contactos, pipelines, calendarios, conversaciones, workflows, funnels y formularios -- todo desde tu asistente de IA.

Creado por [KERS Agency](https://kers.agency).

---

**[Read in English](README.en.md)**

---

## Que es MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) es un estandar abierto que permite a asistentes de IA como Claude interactuar con herramientas y fuentes de datos externas. Este servidor implementa MCP sobre stdio, el transporte estandar para Claude Code.

## Inicio rapido

### Requisitos
- Python 3.10+
- Una cuenta de GoHighLevel con Private Integration

### 1. Clonar

```bash
git clone https://github.com/KERSagency/ghl-mcp-server.git
cd ghl-mcp-server
```

### 2. Instalar dependencias

```bash
pip install mcp requests
```

### 3. Obtener tus credenciales de GHL

Necesitas dos valores de tu subcuenta de GHL:

1. **API Token** -- Settings > Integrations > Private Integrations > Crear nueva > copiar el token
2. **Location ID** -- Settings > Business Profile > copiar el Location ID (empieza por letra, ~20 caracteres)

> **Nota de seguridad:** Estas credenciales dan acceso completo a los datos de tu subcuenta. Nunca las subas a git ni las compartas publicamente.

### 4. Conectar con Claude Code

Anade esto a tu archivo de configuracion MCP. Puedes usar:
- **A nivel de proyecto:** `.mcp.json` en la raiz de tu proyecto
- **A nivel de usuario:** `~/.claude/settings.json`

```json
{
  "mcpServers": {
    "gohighlevel": {
      "command": "python3",
      "args": ["-m", "src.ghl_mcp"],
      "cwd": "/ruta/absoluta/a/ghl-mcp-server",
      "env": {
        "GHL_API_TOKEN": "pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "GHL_LOCATION_ID": "xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

> **Consejo:** En maquinas compartidas o CI, usa variables de entorno del sistema o un archivo `.env` en vez de poner tokens en el config. Ver `.env.example`.

### 5. Verificar

Reinicia Claude Code. Deberias ver "gohighlevel: Connected" en el panel de servidores MCP. Prueba con:

> "Lista mis contactos de GoHighLevel"

## Herramientas disponibles

### Contactos (7 herramientas)
| Herramienta | Descripcion |
|---|---|
| `list_contacts` | Listar/buscar contactos por nombre o email |
| `get_contact` | Ver todos los datos de un contacto por ID |
| `create_contact` | Crear un contacto nuevo |
| `update_contact` | Actualizar campos de un contacto |
| `delete_contact` | Eliminar un contacto (irreversible) |
| `add_contact_tags` | Anadir tags a un contacto |
| `remove_contact_tags` | Quitar tags de un contacto |

### Pipelines y oportunidades (5 herramientas)
| Herramienta | Descripcion |
|---|---|
| `list_pipelines` | Ver todos los pipelines con sus etapas e IDs |
| `search_opportunities` | Buscar oportunidades por pipeline/etapa |
| `create_opportunity` | Crear una oportunidad nueva |
| `update_opportunity` | Mover de etapa, cambiar estado, actualizar valor |
| `delete_opportunity` | Eliminar una oportunidad (irreversible) |

### Calendarios (2 herramientas)
| Herramienta | Descripcion |
|---|---|
| `list_calendars` | Ver todos los calendarios de la subcuenta |
| `get_calendar_events` | Ver eventos en un rango de fechas |

### Conversaciones (3 herramientas)
| Herramienta | Descripcion |
|---|---|
| `search_conversations` | Buscar conversaciones recientes |
| `get_conversation_messages` | Ver mensajes de una conversacion |
| `send_message` | Enviar Email, SMS, WhatsApp o Live Chat |

### Workflows (1 herramienta)
| Herramienta | Descripcion |
|---|---|
| `list_workflows` | Ver todos los workflows y su estado |

### Funnels y formularios (3 herramientas)
| Herramienta | Descripcion |
|---|---|
| `list_funnels` | Ver todos los funnels/websites |
| `get_funnel` | Ver detalle de un funnel con sus paginas |
| `list_forms` | Ver todos los formularios |

**Total: 21 herramientas**

## Ejemplos de uso

Una vez conectado, puedes pedirle a Claude cosas como:

- "Lista mis contactos con el tag 'lead-caliente'"
- "Crea un contacto nuevo: Juan Garcia, juan@email.com, +34666123456"
- "Mueve la oportunidad X a la etapa 'Propuesta enviada'"
- "Que citas tengo esta semana?"
- "Envia un email a este contacto con el siguiente texto..."
- "Que workflows tengo activos?"
- "Lista mis funnels"

## Arquitectura

```
Claude Code <-- stdio --> MCP Server <-- HTTPS --> GoHighLevel API
```

El servidor MCP traduce las llamadas de herramientas MCP a peticiones HTTP contra la [API REST v2 de GoHighLevel](https://highlevel.stoplight.io/docs/integrations). Toda la comunicacion con Claude Code es por stdio (entrada/salida estandar). Toda la comunicacion con GHL es por HTTPS.

## Seguridad

- **Sin credenciales en el codigo** -- los tokens se leen de variables de entorno en tiempo de ejecucion
- **Solo HTTPS** -- todas las llamadas van a `services.leadconnectorhq.com` sobre TLS
- **Sin persistencia de datos** -- nada se escribe a disco; no se guardan logs de datos sensibles
- **Sin llamadas a terceros** -- el servidor solo habla con la API oficial de GHL
- **Dependencias minimas** -- solo `mcp` (de Anthropic) y `requests`
- **Totalmente auditable** -- todo el codigo son ~500 lineas de Python, open source

## Estructura del proyecto

```
ghl-mcp-server/
├── README.md
├── LICENSE              # MIT
├── pyproject.toml       # Metadata y dependencias
├── .env.example         # Plantilla de variables de entorno
├── .gitignore
├── run.sh               # Script de arranque rapido
└── src/
    └── ghl_mcp/
        ├── __init__.py
        ├── __main__.py  # Entry point (python -m src.ghl_mcp)
        ├── server.py    # Servidor MCP + definicion de herramientas
        └── ghl_api.py   # Cliente HTTP para GHL
```

## Contribuir

Has encontrado un bug? Quieres anadir mas endpoints de GHL? Abre un issue o pull request.

## Licencia

MIT -- ver [LICENSE](LICENSE).