n8n Workflow Builder MCP

Un servidor de Model Context Protocol (MCP) para crear y manipular flujos de trabajo (workflows) de n8n. Crea flujos de trabajo de n8n simplemente mediante prompts con IA; funciona con Claude Code, VS Code, Cursor y cualquier cliente compatible con MCP.

VÍDEO DE DEMOSTRACIÓN:

Reglas de Cursor

• El archivo con las reglas se encuentra en rules/n8n-mcp-server-rules.mdc

Related MCP server: MCP- N8N

Características principales

• Gestión de flujos de trabajo: Crea, actualiza y ejecuta flujos de trabajo de n8n mediante programación (la ejecución aún no está implementada)

• Descubrimiento de nodos: Explora los nodos de n8n disponibles y sus capacidades

• Gestión de conexiones: Crea conexiones entre nodos de flujo de trabajo

• Integración con IA: Herramientas especiales para conectar componentes de IA en los flujos de trabajo

• Interfaz amigable para IA: Diseñada específicamente para la interacción con agentes de IA

• Gestión de versiones de N8N: Detección automática de versiones y manejo de compatibilidad; admite más de 184 versiones de n8n (1.86.0 – 2.6.2) con filtrado dinámico de nodos y coincidencia con la "versión inferior más cercana" para compatibilidad con versiones anteriores

Requisitos previos

• Node.js (v18 o superior)

• npm (para el comando npx)

• Un cliente compatible con MCP (Claude Code, VS Code, Cursor, etc.)

Instalación y configuración

Obtención de tu clave API de n8n

1. Abre tu instancia de n8n en un navegador

2. Ve a Settings > API Keys

3. Haz clic en Create API Key

4. Copia la clave generada y úsala en tu configuración

Claude Code (Recomendado)

Agrega el servidor MCP usando la CLI de Claude Code:

claude mcp add n8n-workflow-builder -- npx -y n8n-workflow-builder-mcp

Luego configura las variables de entorno:

claude mcp add n8n-workflow-builder \
  -e N8N_API_URL=http://localhost:5678 \
  -e N8N_API_KEY=your-n8n-api-key-here \
  -- npx -y n8n-workflow-builder-mcp

N8N_VERSION es opcional: el servidor la detecta automáticamente desde la API.

VS Code / Cursor

Agrégalo a tu archivo de configuración de MCP (.vscode/mcp.json para VS Code, .cursor/mcp.json para Cursor):

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["-y", "n8n-workflow-builder-mcp"],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-n8n-api-key-here"
      }
    }
  }
}

Reinicia tu IDE para que los cambios surtan efecto.

Instalación para desarrollo

Para desarrollo o pruebas locales, clona y compila desde el código fuente:

git clone https://github.com/ifmelate/n8n-workflow-builder-mcp.git
cd n8n-workflow-builder-mcp
npm install
npm run build

Luego apunta tu cliente MCP al punto de entrada compilado:

# Claude Code
claude mcp add n8n-workflow-builder -- node /absolute/path/to/n8n-workflow-builder-mcp/dist/index.js

# VS Code / Cursor — use the same JSON config above with "command": "node" and "args": ["/absolute/path/to/dist/index.js"]

Para desarrollo con recompilación automática:

npm run dev

Herramientas MCP disponibles

El servidor proporciona las siguientes herramientas para trabajar con flujos de trabajo de n8n:

Gestión principal de flujos de trabajo

Gestión de nodos

Gestión de conexiones

Planificación y composición de flujos de trabajo

Gestión de parámetros

Plantillas y descubrimiento

Comportamiento de validación

validate_workflow promueve las advertencias a errores y, además, falla cuando cualquier nodo habilitado no está conectado (directamente o a través de puertos de IA) a la cadena principal que comienza en el startNode inferido. Usa connect_from/connect_to o add_ai_connections para corregir la conectividad.

Solución de problemas

General

1. Revisa tu configuración de MCP: asegúrate de que el JSON sea válido y que el nombre del servidor coincida.

2. Actualiza Node.js a la última versión LTS.

3. Limpia la caché de npm si npx falla: npm cache clean --force

4. Intenta una instalación global como alternativa: npm install -g n8n-workflow-builder-mcp

Claude Code

• Ejecuta claude mcp list para verificar que el servidor esté registrado.

• Revisa los registros con claude mcp logs n8n-workflow-builder.

VS Code / Cursor

• Revisa el panel de Salida (Output): selecciona "MCP" en el menú desplegable para ver los registros del servidor.

• Asegúrate de que el servidor esté habilitado en Settings > Features > MCP Servers.

• Reinicia el IDE después de realizar cambios en la configuración.

Estructura del proyecto

• /src: Código fuente principal

• /src/tools: Implementación de herramientas MCP

• /src/models: Modelos de datos

• /src/utils: Funciones de utilidad

• /src/middleware: Autenticación y middleware

• /config: Archivos de configuración

• /tests: Archivos de prueba

• /workflow_nodes: Definiciones de nodos de n8n

• /docs: Documentación adicional

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

1. Haz un fork del repositorio

2. Crea tu rama de funciones (git checkout -b feature/amazing-feature)

3. Confirma tus cambios (git commit -m 'Add some amazing feature')

4. Envía la rama (git push origin feature/amazing-feature)

5. Abre un Pull Request

Licencia

Licencia MIT