ghl-pro-mcp

Servidor MCP local para operar GoHighLevel desde cualquier cliente de IA (Claude Code, Claude Desktop, Codex, Cursor, Cline, Windsurf, VS Code…).

Corre en tu ordenador. Tus credenciales y los datos de tu CRM no pasan por ningún servidor intermedio: el cliente de IA habla directamente con GoHighLevel desde tu máquina.

---

Requisitos

• uv (recomendado), o Python 3.10 o superior.
• Una Private Integration Token de GoHighLevel, creada dentro de la subcuenta que quieras conectar y con los scopes que necesites.

---

Instalación

uv tool install "ghl_pro_mcp-0.1.0-py3-none-any.whl"

Sustituye el nombre por la ruta donde tengas el archivo.

Comprueba que quedó bien:

ghl-pro-mcp --version

Funciona igual en Windows, macOS y Linux.

---

Configuración

Un solo comando:

ghl-pro-mcp setup

Te pide el token privado y el Location ID —y te confirma el nombre de la subcuenta antes de guardar nada—, y después te ofrece configurar workflows y embudos: con la extensión de Chrome, a mano, o dejarlo para más tarde.

Hazlo en una terminal, nunca desde el chat de la IA. Lo que se escribe en la conversación acaba en el historial, y el token privado da acceso completo al CRM.

Las credenciales quedan en un único archivo, en tu carpeta de usuario:

Sistema	Ruta
Windows	%LOCALAPPDATA%\ghl-pro-mcp\credentials.env
macOS	~/Library/Application Support/ghl-pro-mcp/credentials.env
Linux	~/.config/ghl-pro-mcp/credentials.env

Si prefieres decidir tú la ubicación, define GHL_PRO_ENV_PATH y el asistente escribirá ahí: respeta esa variable, igual que el servidor al leer.

---

Añádelo a tu cliente

Al terminar, setup te muestra el bloque exacto que necesitas. Es este:

{
  "mcpServers": {
    "ghl-pro": {
      "command": "ghl-pro-mcp",
      "env": { "GHL_ENABLE_SESSION": "1" }
    }
  }
}

GHL_ENABLE_SESSION enciende workflows y embudos. Sin esa línea tendrás las 548 operaciones de la API pública, pero no el extra — y ese extra es la diferencia: la API pública de GoHighLevel no permite crear ni publicar workflows, así que ninguna otra integración puede hacerlo.

Reinicia tu cliente de IA después de añadirlo.

Cliente	Dónde va
Claude Code	.mcp.json en la raíz de tu proyecto
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · ~/.config/Claude/claude_desktop_config.json (Linux)
Cursor, Cline, Windsurf	Su propio archivo de configuración de MCP

La sintaxis exacta de cada cliente cambia con el tiempo. Consulta su documentación si algo no encaja.

---

Comprobar que funciona

ghl-pro-mcp doctor

Comprueba la configuración contra tu GoHighLevel real y te dice, una a una, qué funciona y qué no. No modifica nada salvo que se lo pidas expresamente.

---

Herramientas

Herramienta	Qué hace
get_account_context	Lista subcuenta, pipelines con etapas, calendarios y usuarios
list_playbooks	Índice de los documentos de conocimiento
get_playbook	Devuelve un documento completo (estrategia, copy, errores conocidos)
list_tags	Todas las etiquetas de la subcuenta
ensure_tags	Crea solo las etiquetas que falten (idempotente)
list_pipelines	Pipelines y sus etapas
search_contacts	Busca contactos por nombre, email o teléfono
create_contact	Crea un contacto

Las escrituras empiezan en seco

Las herramientas que crean algo llevan dry_run=true por defecto: la primera llamada no crea nada, solo muestra lo que haría. Solo se ejecuta de verdad con dry_run=false, después de que el usuario lo confirme.

---

Dónde se guarda cada cosa

Qué	Dónde
El programa	Dentro del paquete instalado (solo lectura)
Tus preferencias e IDs elegidos	Directorio de configuración del sistema
Tus credenciales	Donde tú decidas, vía GHL_PRO_ENV_PATH

El directorio de preferencias, por sistema:

Sistema	Ruta
Windows	%LOCALAPPDATA%\ghl-pro-mcp
macOS	~/Library/Application Support/ghl-pro-mcp
Linux	~/.config/ghl-pro-mcp

---

Diagnóstico

El servidor nunca escribe en stdout salvo el protocolo: todos los logs van a stderr. Si algo falla, sube el detalle con:

GHL_PRO_LOG_LEVEL=DEBUG uvx ghl-pro-mcp

Errores frecuentes:

Síntoma	Causa
«Falta configuración: GHL_PRIVATE_TOKEN»	No definiste la variable o el archivo
«GHL_PRO_ENV_PATH apunta a un archivo que no existe»	Ruta mal escrita
401 al llamar	El token caducó o se revocó
403 al llamar	Al token le falta el scope de esa operación
Faltan datos del catálogo	El paquete se instaló sin la carpeta data/