# n8n MCP Server

Un servidor MCP que le permite a Claude hablar con tu instancia de n8n: listar workflows, ver cuáles están activos, disparar una ejecución y revisar el historial/estado de ejecuciones sin salir del chat.

Trabajo bastante con n8n para automatizaciones (ruteo de leads, notificaciones, sincronizar datos entre APIs) y siempre terminaba metiéndome a la UI de n8n solo para chequear "¿esto corrió bien?" o "¿este workflow está activo?". Esto envuelve la REST API de n8n como tools de MCP para poder preguntarle directo a Claude.

## Qué hace

- `listar_workflows`: lista los workflows, opcionalmente solo los activos
- `ver_workflow`: trae el detalle completo de un workflow (nodos, conexiones, config)
- `ejecutar_workflow`: dispara un workflow (asume que tiene un trigger de webhook, que es como tengo montados la mayoría de los míos)
- `listar_ejecuciones`: lista las últimas ejecuciones, filtrable por workflow
- `ver_ejecucion`: trae el detalle de una ejecución puntual, útil para debuggear por qué falló algo

Los nombres de las tools están en español porque así pienso yo esto en el día a día; las descripciones/docstrings son lo que Claude realmente lee para decidir cuándo usarlas.

## Setup

Necesitás Python 3.10+ y una instancia de n8n con acceso a la API habilitado (Settings > API, generá una key).

```bash
git clone https://github.com/JRGPdev/n8n-mcp-server
cd n8n-mcp-server
python -m venv .venv
.venv\Scripts\activate   # o source .venv/bin/activate en mac/linux
pip install -e ".[dev]"
```

Copiá `.env.example` a `.env` y completá la URL y la API key de tu n8n:

```
N8N_BASE_URL=https://tu-instancia.n8n.cloud
N8N_API_KEY=tu-key-aca
```

Probá que funciona antes de conectarlo a Claude:

```bash
mcp dev src/n8n_mcp/server.py
```

## Conectarlo a Claude Code

```bash
claude mcp add n8n -- python src/n8n_mcp/server.py
```

(asegurate de tener el `.venv` activo, o apuntá directo al path completo del python)

Para Claude Desktop, agregá esto a tu `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "n8n": {
      "command": "python",
      "args": ["C:/path/to/n8n-mcp-server/src/n8n_mcp/server.py"]
    }
  }
}
```

## Correr los tests

```bash
pytest
```

Los tests mockean la API de n8n con respx, así que no necesitás una instancia real corriendo para testear la lógica del cliente.

## Limitaciones conocidas / cosas que agregaría

- `ejecutar_workflow` asume un trigger de webhook. Workflows con trigger manual o solo por schedule no se pueden correr así por la API de n8n, todavía no encontré una forma limpia de resolverlo.
- No hay manejo de paginación en `listar_ejecuciones` más allá del parámetro `limite` que ya soporta n8n.
- Me gustaría agregar una tool para activar/desactivar un workflow, todavía no la necesité.

## Licencia

MIT