mcp-n8n

Opera y construye n8n: 55 herramientas con validación, ediciones quirúrgicas, pruebas de webhook y reversión.

GitHub
21
Prueba este MCPPatrocinado

Documentación

Servidor MCP n8n

npm version npm downloads CI License: MIT TypeScript n8n

Opera y construye n8n desde Cursor o Claude — administración de tu instancia (usuarios, proyectos, ejecuciones, auditoría) y un ciclo completo de construcción: un catálogo de 560 nodos con esquemas de parámetros reales extraídos de los paquetes oficiales de n8n, validación antes de guardar, reparación automática, instantáneas con reversión y diff, depuración de ejecuciones por nodo, informes de salud y copia de seguridad completa de la instancia.

Dos variables de entorno. Se ejecuta en tu máquina (stdio) o como servidor HTTP remoto. Sin cuenta alojada.

🎯 Optimización de Tokens

Este servidor está optimizado para minimizar el consumo de tokens, abordando uno de los mayores problemas de los servidores MCP: el uso excesivo de tokens de API.

Lo que hemos optimizado:

  • Reducción del 90% en tokens para el listado de flujos de trabajo con el nuevo endpoint n8n_list_workflows_summary
  • Filtrado de campos: solicita solo los datos que necesitas
  • Valores predeterminados inteligentes: reducido de 100 a 10-20 resultados por consulta
  • Advertencias inteligentes: alertas cuando las operaciones consumirán tokens significativos

Consulta TOKEN_OPTIMIZATION.md para obtener una guía de uso detallada.

✨ Características

🔄 Gestión de Flujos de Trabajo

  • Crear e Implementar: Construye flujos de trabajo con descripciones en lenguaje natural
  • Operaciones CRUD: Gestión completa del ciclo de vida (Crear, Leer, Actualizar, Eliminar)
  • Control de Activación: Habilita/deshabilita flujos de trabajo bajo demanda
  • Transferencia de Proyectos: Mueve flujos de trabajo entre proyectos sin problemas
  • Gestión de Etiquetas: Organiza flujos de trabajo con etiquetas personalizadas

📊 Monitoreo de Ejecuciones

  • Seguimiento en Tiempo Real: Monitorea ejecuciones de flujos de trabajo con filtros avanzados
  • Información Detallada: Accede a datos completos de ejecución y registros
  • Recuperación de Errores: Reintenta ejecuciones fallidas automáticamente
  • Herramientas de Limpieza: Gestiona el historial de ejecuciones de manera eficiente

🔐 Gestión de Credenciales

  • Creación Segura: Agrega credenciales para cualquier servicio
  • Descubrimiento de Esquemas: Descubre automáticamente los campos requeridos para tipos de credenciales
  • Aislamiento de Proyectos: Transfiere credenciales entre proyectos de forma segura
  • Soporte de Tipos: Compatible con todos los tipos de credenciales de n8n

🧱 Constructor de Flujos de Trabajo

  • Catálogo completo de nodos — 560 nodos con esquemas reales: extraídos directamente de n8n-nodes-base y @n8n/n8n-nodes-langchain (parámetros con tipos, opciones permitidas, condiciones de visualización, credenciales, última typeVersion), regenerados semanalmente por CI. Busca con n8n_search_nodes, inspecciona con n8n_get_node
  • Validación real: n8n_validate_workflow verifica contra los esquemas reales — tipos de nodo inexistentes, parámetros requeridos faltantes (incluidos los condicionalmente requeridos), valores de opción inválidos, typeVersion incorrecta, conexiones rotas — antes de guardar/activar
  • Linting de expresiones: detecta expresiones {{ }} que carecen del prefijo = y referencias a nodos que no existen en el flujo de trabajo
  • Reparación automática: n8n_autofix_workflow corrige typeVersion/posiciones faltantes, nombres duplicados, conexiones colgantes y prefijos de expresiones — previsualiza primero, aplica con una instantánea
  • Ediciones quirúrgicas: n8n_update_workflow_partial agrega/elimina nodos y conexiones sin reescribir todo el flujo
  • Plantillas públicas: busca e importa desde n8n.io (n8n_search_public_templates, n8n_import_public_template) más 100 plantillas incluidas como respaldo
  • Prompts guiados: los prompts MCP build-workflow y fix-workflow guían a cualquier agente a través del ciclo completo de construir/validar/probar/reparar

🔬 Depuración Profunda y Salud

  • Datos de ejecución por nodo: n8n_get_node_execution_data muestra exactamente qué datos fluyeron a través de un nodo (estado, conteos de elementos, muestras de salida, detalles de error) sin descargar toda la ejecución
  • Ciclo de depuración: n8n_debug_last_error devuelve el nodo fallido y el mensaje del último error
  • Informes de salud: n8n_workflow_health calcula la tasa de éxito, el número de fallos, la duración promedio y el último fallo por flujo de trabajo a partir de ejecuciones recientes, ordenados de peor a mejor

🛡️ Red de Seguridad y Pruebas Reales

  • Instantáneas automáticas: antes de cada actualización, edición parcial, corrección automática o eliminación, el estado anterior se guarda localmente (~/.mcp-n8n/snapshots, configurable con N8N_SNAPSHOT_DIR)
  • Reversión: n8n_rollback_workflow restaura cualquier instantánea — incluso recrea un flujo de trabajo eliminado (recreate=true)
  • Diff: n8n_diff_workflow_snapshot compara una instantánea contra el estado actual (nodos agregados/eliminados/modificados, parámetros cambiados, cambios de conexión) antes de decidir revertir
  • Copia de seguridad completa de la instancia: n8n_export_all_workflows guarda cada flujo de trabajo como archivos JSON; n8n_import_workflows los restaura
  • Pruebas de extremo a extremo: n8n_trigger_webhook llama a un flujo de trabajo activado por Webhook en la instancia y devuelve la respuesta HTTP real, para que el agente pueda verificar que el flujo realmente funciona

🎯 Plantillas Incluidas

  • 100 puntos de partida locales con coincidencia de palabras clave, si prefieres no usar n8n.io

🏗️ Organización y Administración

  • Etiquetas: Categoriza y organiza recursos
  • Variables: Gestión centralizada de variables de entorno
  • Proyectos: Soporte multiinquilino de proyectos
  • Usuarios y Permisos: Gestión completa del control de acceso
  • Registros de Auditoría: Genera informes de seguridad y cumplimiento

🚀 Inicio Rápido

Instalación mediante npm (Recomendado)

Esta es la forma más fácil de comenzar:

npm install -g mcp-n8n

Configuración

  1. Obtén tus credenciales de API de n8n:

    • Navega a tu instancia de n8n → Configuración → API de n8n
    • Genera una nueva clave de API

  2. Configura Claude Desktop:

Agrega a ~/Library/Application Support/Claude/claude_desktop_config.json (Mac/Linux) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

Opción A - Usando instalación global (si ejecutaste npm install -g mcp-n8n):

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS es opcional (all por defecto). Usa core,builder si deseas operaciones + creación sin herramientas de administración de usuarios/proyectos. Usa admin solo para administración de la instancia.

Modo HTTP remoto (opcional)

Por defecto, el servidor se comunica a través de stdio (local). Para ejecutarlo como servidor remoto compartido (por ejemplo, en Docker o en un VPS), establece un puerto:

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

Esto expone el protocolo MCP a través de HTTP transmisible en el puerto 3000 más un endpoint GET /health. N8N_MCP_HTTP_TOKEN es muy recomendable: cuando se establece, cada solicitud debe incluir Authorization: Bearer <token>. Apunta cualquier cliente MCP que admita HTTP transmisible a http://your-host:3000 con ese encabezado.

Opción B - Usando npx (sin necesidad de instalación, siempre la última versión):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}
  1. Configura Cursor:

Agrega a la configuración MCP de Cursor (Configuración → Extensiones → MCP):

Recomendado - Usando npx (siempre usa la última versión):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Nota: Cursor requiere usar npx para servidores MCP. El indicador -y instala/actualiza automáticamente el paquete sin preguntar.

Opción C - Docker:

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

El volumen /data persiste las instantáneas de flujos de trabajo entre ejecuciones.

  1. Reinicia Claude Desktop o Cursor

💬 Ejemplos de Uso

Una vez configurado, interactúa con n8n usando lenguaje natural:

Creación de Flujos de Trabajo

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

Uso de Plantillas

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

Gestión de Flujos de Trabajo

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

Monitoreo y Depuración

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"

"Delete all successful executions older than 30 days"

🛠️ Herramientas Disponibles

Flujos de Trabajo
  • n8n_create_workflow - Crea nuevos flujos de trabajo (valida primero)
  • n8n_list_workflows_summary - Listado eficiente en tokens
  • n8n_list_workflows - Detalles completos con filtrado de campos opcional
  • n8n_get_workflow - JSON completo del flujo de trabajo
  • n8n_update_workflow - Reemplaza campos (los campos omitidos mantienen los valores actuales)
  • n8n_update_workflow_partial - Ediciones quirúrgicas: agrega/elimina nodos y conexiones
  • n8n_delete_workflow - Elimina flujos de trabajo permanentemente
  • n8n_activate_workflow / n8n_deactivate_workflow
  • n8n_transfer_workflow / herramientas de etiquetas
Seguridad y Pruebas
  • n8n_list_workflow_snapshots - Historial local de cada cambio realizado a través de este servidor
  • n8n_rollback_workflow - Restaura una versión anterior, o recrea un flujo de trabajo eliminado
  • n8n_diff_workflow_snapshot - Compara una instantánea contra el estado actual antes de revertir
  • n8n_trigger_webhook - Llama a un flujo de trabajo de webhook y obtiene la respuesta real
  • n8n_export_all_workflows / n8n_import_workflows - Copia de seguridad y restauración completa de la instancia
Constructor
  • n8n_search_nodes / n8n_get_node - Catálogo completo: 560 nodos con esquemas de parámetros reales
  • n8n_validate_workflow - Verifica JSON contra esquemas reales antes de guardar/activar
  • n8n_autofix_workflow - Reparaciones mecánicas: typeVersion, posiciones, duplicados, conexiones colgantes, prefijos de expresiones
  • n8n_search_public_templates / n8n_import_public_template - Biblioteca oficial de n8n.io
  • n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template - Plantillas incluidas

100 Plantillas Incluidas en 13 categorías:

  • Comercio electrónico: automatización de Shopify, agentes de soporte de WooCommerce
  • Redes sociales: automatización de Instagram, TikTok, LinkedIn, Twitter
  • IA/Chat: Chatbots, agentes de IA, asistentes de voz
  • Comunicación: automatización de WhatsApp, Telegram, Email
  • Contenido: automatización de blogs, generación de video, optimización SEO
  • RRHH/Reclutamiento: selección de currículos, búsqueda de candidatos
  • Ventas/CRM: generación de leads, pipelines de llamadas en frío
  • Finanzas: análisis de acciones, extracción de facturas
  • Raspado de datos: Google Maps, LinkedIn, Amazon, TikTok
  • Monitoreo: tiempo de actividad del sitio web, seguimiento de competidores
  • Productividad: automatización de calendario, Notion, programación
Ejecuciones (4 herramientas)
  • n8n_list_executions - Filtra por estado, flujo de trabajo, proyecto
  • n8n_get_execution - Datos detallados de ejecución
  • n8n_delete_execution - Elimina registros de ejecución
  • n8n_retry_execution - Reintenta ejecuciones fallidas
  • n8n_debug_last_error - Nodo fallido + mensaje del último error
  • n8n_get_node_execution_data - Datos que fluyeron a través de un nodo específico
  • n8n_workflow_health - Tasa de éxito, fallos y duración por flujo de trabajo
Credenciales (4 herramientas)
  • n8n_create_credential - Agrega nuevas credenciales
  • n8n_delete_credential - Elimina credenciales (solo propietario)
  • n8n_get_credential_schema - Descubre campos requeridos
  • n8n_transfer_credential - Mueve entre proyectos
Organización (19 herramientas)

Etiquetas: Crear, listar, obtener, actualizar, eliminar Variables: Crear, listar, actualizar, eliminar Usuarios: Listar, crear, obtener, eliminar, cambiar rol Proyectos: Crear, listar, actualizar, eliminar, gestionar usuarios

Avanzado (2 herramientas)
  • n8n_generate_audit - Informes de auditoría de seguridad
  • n8n_pull_source_control - Integración de control de versiones

61 herramientas por defecto (N8N_TOOLSETS=all). core,builder expone 28. Más 2 prompts MCP (build-workflow, fix-workflow).

📚 Documentación

🏗️ Estructura del Proyecto

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

🔧 Desarrollo

Instalación Local (Para Desarrollo)

Si deseas contribuir o probar cambios locales:

1. Configuración

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. Configura con Compilación Local

Para Claude Desktop, agrega a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Para Cursor, agrega a la configuración MCP:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Importante: Reemplaza /absolute/path/to/mcp-n8n/ con la ruta absoluta real a tu repositorio clonado (por ejemplo, /Users/yourname/projects/mcp-n8n/).

3. Pruebas

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

Cómo Ejecutar

Para ejecutar el script principal, ejecuta:

python main.py

Cómo Probar

Para ejecutar las pruebas, ejecuta:

pytest test_main.py

📋 Requisitos

  • Node.js: 20 o superior
  • Instancia de n8n: Autoalojada o n8n Cloud (plan de pago)
  • Clave API de n8n: Requerida para autenticación
  • IDE con IA: Claude Desktop o Cursor con soporte MCP

Requisitos de n8n

  • Autoalojado: Acceso completo a la API ✅
  • n8n Cloud: Requiere plan de pago para acceso a la API
  • Versión: Compatible con n8n v1.0.0+

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

  1. Haz un fork del repositorio
  2. Crea tu rama de funcionalidad (git checkout -b feature/AmazingFeature)
  3. Haz commit de tus cambios (git commit -m 'Add some AmazingFeature')
  4. Haz push a la rama (git push origin feature/AmazingFeature)
  5. Abre un Pull Request

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

  • n8n - La plataforma de automatización de flujos de trabajo
  • Anthropic - Claude y el Protocolo de Contexto de Modelos
  • Cursor - Editor de código impulsado por IA

🔗 Recursos

⚠️ Notas Importantes

Acceso a la API

  • n8n Cloud requiere un plan de pago para acceder a la API
  • n8n autoalojado tiene acceso completo a la API en todos los planes
  • Algunas operaciones requieren permisos de propietario/administrador

Seguridad

  • Nunca hagas commit de archivos .env con credenciales
  • Usa variables de entorno para datos sensibles
  • Las claves API otorgan acceso completo a tu instancia de n8n
  • Rota las claves API regularmente por seguridad

Límites de Tasa

  • Respeta los límites de tasa de la API de n8n
  • Usa paginación para conjuntos de resultados grandes
  • Implementa manejo de errores para respuestas de límite de tasa

🐛 Solución de Problemas

Problemas de Conexión

Problema: "No se puede conectar a la API de n8n"

  • Verifica que N8N_BASE_URL sea correcto y accesible
  • Comprueba que la clave API sea válida
  • Asegúrate de que la instancia de n8n esté en ejecución

Errores de Permisos

Problema: "Permisos insuficientes"

  • Algunas operaciones requieren el rol de propietario/administrador
  • Verifica que tu usuario tenga los permisos adecuados
  • Comprueba los derechos de acceso a nivel de proyecto

Problemas con Plantillas

Problema: "Plantilla no encontrada"

  • Asegúrate de que el directorio examples/ esté presente
  • Verifica que templates-metadata.json exista
  • Comprueba que las referencias a archivos de plantilla sean correctas

💡 Consejos y Buenas Prácticas

  1. Comienza con Plantillas: Usa plantillas preconstruidas como punto de partida
  2. Usa Etiquetas: Organiza los flujos de trabajo con etiquetas para una gestión fácil
  3. Monitorea Ejecuciones: Revisa regularmente las ejecuciones fallidas
  4. Limpieza: Elimina datos de ejecución antiguos para ahorrar espacio
  5. Control de Versiones: Usa las funciones integradas de control de versiones de n8n
  6. Prueba Primero: Prueba los flujos de trabajo antes de activarlos en producción

📧 Soporte