Metadata-Version: 2.5
Name: ghl-pro-mcp
Version: 0.1.1
Summary: Servidor MCP local para operar GoHighLevel desde cualquier cliente de IA: workflows, embudos, landings con IA, contactos, pipelines, archivos y mensajes.
License: Proprietary
Keywords: automation,crm,funnels,gohighlevel,mcp,model-context-protocol,workflows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2
Requires-Dist: platformdirs>=4
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```powershell
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:

```powershell
ghl-pro-mcp --version
```

Funciona igual en **Windows, macOS y Linux**.

---

## Configuración

**Un solo comando:**

```powershell
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:

```json
{
  "mcpServers": {
    "ghl-pro": {
      "command": "uvx",
      "args": ["ghl-pro-mcp@latest"],
      "env": { "GHL_ENABLE_SESSION": "1" }
    }
  }
}
```

**No hay que instalar nada a mano:** `uvx` se lo baja de PyPI y lo ejecuta. Es el
equivalente a `npx`. El `@latest` hace que compruebe si hay versión nueva cada vez, así
que los arreglos llegan solos.

> Hace falta `uv`: `winget install astral-sh.uv`, o
> `curl -LsSf https://astral.sh/uv/install.sh | sh`.

`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

```powershell
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:

```bash
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/` |
