n8n-mcp

El servidor MCP más completo para n8n: 43 herramientas, 8 plantillas de prompts y 6 recursos navegables que cubren toda la superficie de la API REST de n8n. La primera implementación en Python.

Dale a Claude (o a cualquier cliente de IA compatible con MCP) control total sobre tu instancia de n8n: crea flujos de trabajo, ejecuta procesos, gestiona credenciales, consulta tablas de datos, realiza auditorías de seguridad, todo a través de lenguaje natural.

Aspectos destacados

• 43 herramientas MCP — CRUD completo para flujos de trabajo, ejecuciones, credenciales, etiquetas, variables y tablas de datos, además de operaciones administrativas como auditorías de seguridad y descubrimiento de capacidades de la API.

• Creación de flujos de trabajo con doble validación — create_and_validate_workflow ejecuta un pipeline de 6 fases: creación, verificación de lectura estructural, dos pasadas de ejecución, comparación de consistencia y un veredicto de APROBADO/FALLIDO.

• Seguridad de escritura por defecto — Todas las operaciones de mutación están deshabilitadas a menos que las habilites explícitamente con N8N_MCP_WRITE_MODE=true.

• 8 plantillas de prompts guiadas — Flujos de trabajo de IA de varios pasos para depuración, comprobaciones de estado, revisiones de seguridad, creación de flujos de trabajo con pruebas completas y más.

• Asíncrono y paginado — Construido sobre httpx con paginación automática basada en cursores y tiempos de espera configurables.

Características

Además de 8 plantillas de prompts MCP y 6 recursos navegables.

Requisitos previos

• Python 3.10+

• Instancia de n8n — local (Docker) o remota (alojada en la nube)

• Clave de API de n8n — generada desde la configuración de n8n

Inicio rápido

1. Clonar e instalar

git clone https://github.com/Siddharth0903/n8n-mcp.git
cd n8n-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Iniciar n8n (si no tienes uno ejecutándose)

docker compose up -d

Esto inicia n8n con PostgreSQL en http://localhost:5678.

3. Obtener tu clave de API de n8n

1. Abre http://localhost:5678 en tu navegador

2. Completa la configuración inicial si es una instancia nueva

3. Ve a Settings (icono de engranaje) > n8n API

4. Haz clic en Create an API key

5. Copia la clave

4. Configurar el entorno

cp .env.example .env

Edita .env con tus valores:

N8N_MCP_BASE_URL=http://localhost:5678   # Your n8n URL
N8N_MCP_API_KEY=your-api-key-here        # The API key from step 3
N8N_MCP_WRITE_MODE=false                 # Set to 'true' to enable create/update/delete

5. Ejecutar el servidor

n8n-mcp

El servidor MCP ahora se está ejecutando sobre stdio, listo para que cualquier cliente MCP se conecte.

Integración con clientes

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "n8n": {
      "command": "/absolute/path/to/your/.venv/bin/n8n-mcp",
      "env": {
        "N8N_MCP_BASE_URL": "http://localhost:5678",
        "N8N_MCP_API_KEY": "your-api-key-here",
        "N8N_MCP_WRITE_MODE": "true"
      }
    }
  }
}

Consejo: Usa la ruta absoluta completa al binario n8n-mcp dentro de tu virtualenv.

Claude Code (CLI)

claude mcp add n8n -- /absolute/path/to/your/.venv/bin/n8n-mcp

O añade a .mcp.json de tu proyecto:

{
  "mcpServers": {
    "n8n": {
      "command": "/absolute/path/to/your/.venv/bin/n8n-mcp",
      "env": {
        "N8N_MCP_BASE_URL": "http://localhost:5678",
        "N8N_MCP_API_KEY": "your-api-key-here",
        "N8N_MCP_WRITE_MODE": "true"
      }
    }
  }
}

Cualquier cliente MCP

n8n-mcp utiliza el transporte estándar MCP stdio. Cualquier cliente compatible con MCP puede conectarse iniciando el binario n8n-mcp.

Configuración

Todos los ajustes se configuran mediante variables de entorno (o archivo .env):

Recursos MCP

Vistas de solo lectura navegables de tus datos de n8n:

Prompts MCP

Plantillas guiadas de varios pasos que guían a la IA a través de operaciones complejas:

Seguridad

• El modo de escritura está DESACTIVADO por defecto — solo funcionan las operaciones de lectura hasta que establezcas explícitamente N8N_MCP_WRITE_MODE=true.

• Los secretos de las credenciales nunca se exponen — la API de n8n solo devuelve metadatos, nunca valores secretos.

• Validación de ruta de webhook — evita ataques de recorrido de ruta y SSRF.

• Respuestas de error estructuradas — cada error devuelve un JSON procesable con sugerencias, no excepciones sin procesar.

• Tiempos de espera de solicitud — los tiempos de espera configurables evitan conexiones bloqueadas.

Arquitectura

Claude / MCP Client
        |
        v
  +-----------+
  |  n8n-mcp  |  FastMCP server (Python, async)
  |           |
  | 43 tools  |  Workflows, Executions, Credentials,
  | 6 rsrc    |  Tags, Variables, Data Tables, Admin
  | 8 prompts |
  +-----+-----+
        | httpx (async, paginated)
        v
  +-----------+
  |  n8n API  |  REST /api/v1
  +-----+-----+
        |
        v
  +-----------+
  | Workflows |
  |  & Data   |
  +-----------+

Desarrollo

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Lint
ruff check src/ tests/

# Type check
mypy src/

Licencia

MIT