AutomateLab n8n

Construye flujos de trabajo de n8n, nodos personalizados y agentes de IA a partir de lenguaje natural. Se combina con el servidor @automatelab/n8n-mcp.

GitHub

Prueba este MCPPatrocinado

Documentación

n8n-mcp

Un servidor MCP para n8n que proporciona a Claude, Cursor y otros agentes de IA herramientas para generar flujos de trabajo, hacer linting, diagnosticar ejecuciones fallidas y manejar instancias de n8n en vivo.

Por qué lo construimos

Usamos n8n a diario dentro de AutomateLab y seguíamos encontrando los mismos fallos de LLM: JSON de flujo de trabajo que se importa pero falla en tiempo de ejecución, clústeres de AI Agent conectados con tipos de conexión incorrectos, ejecuciones que descartan elementos silenciosamente sin pista de dónde mirar. Volcar todo el catálogo de n8n en el contexto no lo soluciona: los modos de fallo son demasiado sutiles (desajustes de typeVersion, esquema IF v1, credenciales que no sobreviven a la importación).

Así que construimos un servidor pequeño y enfocado: codificar los modos de fallo que el lint puede detectar, la topología de clúster que el generador debe respetar y el diagnóstico que el agente no puede hacer solo. Para un recorrido por las nueve herramientas con ejemplos de salida, consulta el artículo de lanzamiento en automatelab.tech.

Por qué es diferente

Otros servidores MCP de n8n (notablemente czlonkowski/n8n-mcp) compiten en amplitud: más de 20 herramientas y un corpus indexado de cada nodo de n8n. Ellos dominan ese nicho.

Este servidor es el MCP de depuración y corrección en el primer uso para n8n:

execution_explain es la cuña. Pega el JSON de ejecución; obtén hallazgos por nodo: qué nodos devolvieron 0 elementos, cuáles tenían expresiones ={{ ... }} sin resolver, mensajes de error con pistas concretas. Ningún otro servidor MCP hace esto bien, y aborda el punto de dolor número 1 de depuración de la comunidad de n8n (pérdida silenciosa de datos entre nodos).
workflow_generate es opinado sobre la topología de AI Agent: emite clústeres LangChain adecuados con conexiones ai_languageModel / ai_memory / ai_tool (los sub-nodos se conectan hacia arriba al agente, no mediante main). Se importa limpiamente en n8n 1.x.
workflow_lint detecta los fallos silenciosos: tipos de nodo obsoletos (Function → Code, spreadsheetFile → convertToFile), AI Agent sin modelo de lenguaje, esquema IF v1, Webhook sin webhookId, conexiones rotas en todos los tipos de conexión (no solo main).
5 herramientas REST (controladas por N8N_API_URL + N8N_API_KEY) te permiten listar, obtener, crear, activar flujos de trabajo y extraer ejecuciones, para que las herramientas de lint y explicación puedan ejecutarse contra tus flujos de trabajo en vivo, no solo contra JSON pegado en el chat.

Además: una Agent Skill emparejada que enseña al modelo cuándo usar cada herramienta y dónde cargar contexto más profundo (dividida en references/ para no inflar el prompt).

Herramientas

Los nombres de las herramientas siguen la notación de puntos y forman un árbol navegable: node.*, workflow.*, execution.*. Cada herramienta declara un outputSchema (para que los llamadores puedan verificar tipos en las respuestas) y MCP annotations (pistas de solo lectura / destructivo / idempotente / mundo abierto).

Sin estado (funcionan sin una instancia de n8n en vivo):

Herramienta	Propósito
`workflow_generate`	Descripción en lenguaje natural → JSON de flujo de trabajo. Detecta intención de agente de IA.
`node_scaffold`	Descripción → archivo TypeScript `INodeType` único para un paquete personalizado de n8n.
`workflow_lint`	JSON de flujo de trabajo → lista de errores y advertencias (más de 20 reglas).
`workflow_diff`	Dos flujos de trabajo → diff semántico (nodos añadidos/eliminados/modificados, conexiones, ajustes).
`execution_explain`	JSON de ejecución fallida → diagnóstico por nodo con pistas.
`execution_replay`	Flujo de trabajo + nodo → flujo de trabajo de reproducción autocontenido que ejercita solo ese nodo.
`execution_timeline`	JSON de ejecución → tabla de línea de tiempo por nodo (inicio, duración, elementos entrantes/salientes, errores).

Instancia en vivo (requieren las variables de entorno N8N_API_URL + N8N_API_KEY):

Herramienta	Propósito
`workflow_list`	Paginar flujos de trabajo; filtrar por activo/etiquetas/nombre.
`workflow_get`	Obtener un flujo de trabajo por id.
`workflow_create`	Enviar un flujo de trabajo por POST. Elimina campos de solo lectura.
`workflow_activate`	Cambiar activo/desactivado.
`execution_list`	Explorar ejecuciones; pasa `includeData: true` para el cuerpo completo.

Cambios en v0.5.0. Tres nuevas herramientas: workflow_diff, execution_replay, execution_timeline. Lint ampliado con 10 nuevas reglas (límite de tasa, deriva de credenciales, expresiones obsoletas, sandbox de código, ruta de prueba de webhook, manualTrigger en activo, riesgo de horario DST, desactivado pero conectado, Set vacío, desajuste de método/cuerpo HTTP). Nuevas variables de entorno de política de ejecución: N8N_MCP_READ_ONLY, N8N_MCP_DISABLED_TOOLS, N8N_MCP_ALLOWED_WORKFLOW_IDS, N8N_MCP_ALLOWED_TAGS. Paquete DXT + Dockerfile + configuraciones de despliegue para Render/Railway/Fly.

Cambio importante en v0.4.0. Las herramientas fueron renombradas de n8n_* (snake_case) a notación de puntos. Actualiza cualquier prompt, habilidad de agente o script que haga referencia a los nombres antiguos.

Política de ejecución (v0.5+)

Restringe el servidor sin bifurcarlo. Establece estas variables de entorno antes de lanzarlo:

Variable de entorno	Efecto
`N8N_MCP_READ_ONLY=1`	Desactiva `workflow_create`, `workflow_activate`, `node_scaffold`.
`N8N_MCP_DISABLED_TOOLS=workflow_create,workflow_activate`	Omite por completo el registro de esas herramientas.
`N8N_MCP_ALLOWED_WORKFLOW_IDS=abc,def`	Las herramientas REST se niegan a tocar cualquier flujo de trabajo fuera de la lista.
`N8N_MCP_ALLOWED_TAGS=prod,staging`	`workflow_list` filtra a flujos de trabajo que tengan al menos una etiqueta.

Útil cuando se entrega el MCP a un agente junior o se conecta detrás de un asistente orientado al cliente.

Despliegue

Claude Desktop con un clic: construye el paquete .dxt desde dxt/manifest.json (ver dxt/README.md).
Docker: docker build -t n8n-mcp . && docker run --rm -i -e N8N_API_URL=... -e N8N_API_KEY=... n8n-mcp.
Render: coloca render.yaml y haz clic en "Nuevo desde Blueprint".
Railway: railway.toml — railway up en la raíz del repositorio.
Fly.io: fly.toml — fly launch --copy-config.

Instalación

Requiere Node 20 o posterior.

Como herramienta CLI

npm install -g @automatelab/n8n-mcp

Como GitHub Action

Usa la GitHub Action de n8n MCP para hacer lint de flujos de trabajo, diagnosticar ejecuciones y generar JSON de flujo de trabajo en tu pipeline de CI/CD:

- uses: ratamaha-git/n8n-mcp@v1
  with:
    command: 'lint'
    workflow-json: ${{ env.WORKFLOW_JSON }}

Consulta ACTION.md y GITHUB-ACTION-SETUP.md para ejemplos y detalles de publicación.

Configura tu host MCP

Cursor (~/.cursor/mcp.json) o Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "n8n_..."
      }
    }
  }
}

El bloque env es opcional: las 4 herramientas sin estado funcionan sin él. Obtén una clave API de n8n: Configuración → API → Crear clave API.

Reinicia tu host MCP. Las 12 herramientas con notación de puntos (workflow.*, node.*, execution.*) aparecen en el panel MCP.

Ejemplos de herramientas

`workflow_generate`

Usa workflow_generate para construir: webhook de Stripe → mensaje de Slack + nueva fila en Google Sheets.

Devuelve JSON de flujo de trabajo listo para el diálogo 'Importar desde archivo' de n8n.

`execution_explain`

Aquí hay una ejecución fallida de n8n. ¿Por qué no se dispara el nodo de Slack? [pegar JSON]

Devuelve:

WARNING [Filter] Returned 0 items. Downstream nodes will not execute.
  hint: Common causes: (1) IF/Switch routed to the other branch — check `parameters.conditions`. (2) Filter/Set node dropped everything — inspect its output explicitly.

INFO [Last node executed was "Filter". If the workflow stopped here unexpectedly, check its output items below.]

`workflow_lint`

Haz lint de este JSON de flujo de trabajo. [pegar JSON]

Devuelve:

ERROR [AI Agent] AI Agent has no `ai_languageModel` sub-node connected. Attach a chat model (e.g. lmChatOpenAi).
WARNING [Webhook] Webhook node has no `webhookId`. n8n auto-generates one on import, so the production URL will change.
WARNING [LegacyFunction] Node type "n8n-nodes-base.function" is deprecated. Use "n8n-nodes-base.code".

O no issues found.

Ejemplos

El directorio examples/ incluye dos flujos de trabajo listos para importar:

workflow-stripe-to-slack.json - El webhook de Stripe se distribuye a Slack y Google Sheets.
workflow-rss-to-discord.json - El disparador de feed RSS publica nuevos elementos en un canal de Discord.

Importa cualquiera de ellos mediante el diálogo Importar desde archivo de n8n.

Desarrollo

git clone https://github.com/ratamaha-git/n8n-mcp
cd n8n-mcp
npm install
npm run build
npm run smoke

npm run smoke inicia el servidor con una bandera --smoke que lista las herramientas registradas y sale sin vincular stdio. Útil para CI o comprobaciones de cordura en el primer uso.

Licencia

MIT. Consulta LICENSE.

Desarrollado por AutomateLab.