Servidor MCP n8n

Opera y crea n8n desde Cursor o Claude — administración de tu instancia (usuarios, proyectos, ejecuciones, auditoría) y un bucle de creación completo: 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.

Qué 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

• Avisos inteligentes: alertas cuando las operaciones van a consumir una cantidad significativa de tokens

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

Related MCP server: n8n Workflow Builder

✨ Características

🔄 Gestión de flujos de trabajo

• Crear e implementar: crea 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

📊 Supervisión de ejecuciones

• Seguimiento en tiempo real: supervisa las ejecuciones de flujos de trabajo con filtros avanzados

• Información detallada: accede a los datos completos de ejecución y registros

• Recuperación de errores: reintenta automáticamente las ejecuciones fallidas

• Herramientas de limpieza: gestiona el historial de ejecuciones de manera eficiente

🔐 Gestión de credenciales

• Creación segura: añade credenciales para cualquier servicio

• Descubrimiento de esquemas: descubre automáticamente los campos obligatorios para los 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

🧱 Creador 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 comprueba los esquemas reales — tipos de nodo inexistentes, parámetros obligatorios faltantes (incluidos los condicionalmente obligatorios), valores de opción no válidos, typeVersion incorrecta, conexiones rotas — antes de guardar/activar

• Linting de expresiones: detecta expresiones {{ }} a las que les falta el 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 añade/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) además de 100 plantillas incluidas como respaldo

• Indicaciones guiadas: los prompts MCP build-workflow y fix-workflow guían a cualquier agente a través del bucle completo de creación/validación/prueba/reparación

🔬 Depuración avanzada 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, recuentos de elementos, muestras de salida, detalles de error) sin descargar toda la ejecución

• Bucle de depuración: n8n_debug_last_error devuelve el nodo 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 media 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 con el estado actual (nodos añadidos/eliminados/modificados, parámetros cambiados, cambios en las conexiones) antes de decidir revertir

• Copia de seguridad de la instancia completa: 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 con disparador 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 acceder a n8n.io

🏗️ Organización y administración

• Etiquetas: categoriza y organiza recursos

• Variables: gestión centralizada de variables de entorno

• Proyectos: soporte de proyectos multiinquilino

• 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 sencilla de empezar:

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:

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

Opción A: usar la 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 quieres operaciones + creación sin herramientas de administración de usuarios/proyectos. Usa admin solo para la 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 (p. ej., 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 además de un endpoint GET /health. Se recomienda encarecidamente N8N_MCP_HTTP_TOKEN: cuando se establece, cada solicitud debe incluir Authorization: Bearer <token>. Apunta cualquier cliente MCP que admita HTTP transmisible a http://tu-host:3000 con esa cabecera.

Opción B: usar 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"
      }
    }
  }
}

3. Configura Cursor:

Añade a la configuración MCP de Cursor (Configuración → Extensiones → MCP):

Recomendado: usar 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 los servidores MCP. El indicador -y instala/actualiza el paquete automáticamente 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.

4. 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?"

Supervisión 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

• 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 conservan los valores actuales)

• n8n_update_workflow_partial - Ediciones quirúrgicas: añade/elimina nodos y conexiones

• n8n_delete_workflow - Elimina flujos de trabajo permanentemente

• n8n_activate_workflow / n8n_deactivate_workflow

• n8n_transfer_workflow / herramientas de etiquetas

• 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 con el estado actual antes de revertir

• n8n_trigger_webhook - Llama a un flujo de trabajo webhook y obtén la respuesta real

• n8n_export_all_workflows / n8n_import_workflows - Copia de seguridad y restauración de la instancia completa

• n8n_search_nodes / n8n_get_node - Catálogo completo: 560 nodos con esquemas de parámetros reales

• n8n_validate_workflow - Comprueba el JSON contra los 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, correo electrónico

• Contenido: automatización de blogs, generación de vídeo, optimización SEO

• RR. HH./Reclutamiento: selección de currículos, búsqueda de candidatos

• Ventas/CRM: generación de clientes potenciales, canalizaciones de llamadas en frío

• Finanzas: análisis de acciones, extracción de facturas

• Raspado de datos: Google Maps, LinkedIn, Amazon, TikTok

• Supervisión: tiempo de actividad del sitio web, seguimiento de la competencia

• Productividad: automatización de calendario, Notion, programación

• 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 con error + 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

• n8n_create_credential - Añade nuevas credenciales

• n8n_delete_credential - Elimina credenciales (solo propietario)

• n8n_get_credential_schema - Descubre los campos obligatorios

• n8n_transfer_credential - Mueve entre proyectos

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

• 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. Además de 2 prompts MCP (build-workflow, fix-workflow).

📚 Documentación

• Guía de inicio rápido - Ponte en marcha en 5 minutos

• Ejemplos y casos de uso - Ejemplos de automatización del mundo real

• Referencia de nodos - Documentación detallada de las herramientas

• Registro de cambios - Historial de versiones y actualizaciones

🏗️ 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 quieres 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. Configuración con compilación local

Para Claude Desktop, añade 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, añade a la configuración de 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 de tu repositorio clonado (p. ej., /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: Self-hosted o n8n Cloud (plan de pago)

• Clave API de n8n: Requerida para la autenticación

• IDE de IA: Claude Desktop o Cursor con soporte para MCP

Requisitos de n8n

• Self-hosted: 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 características (git checkout -b feature/AmazingFeature)

3. Haz commit de tus cambios (git commit -m 'Add some AmazingFeature')

4. Sube 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

• Documentación de la API de n8n

• Protocolo de Contexto de Modelos

• Comunidad de n8n

• Registro de servidores MCP

⚠️ Notas importantes

Acceso a la API

• n8n Cloud requiere un plan de pago para acceder a la API

• n8n self-hosted 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 periódicamente por seguridad

Límites de velocidad

• Respeta los límites de velocidad de la API de n8n

• Usa paginación para conjuntos de resultados grandes

• Implementa manejo de errores para respuestas de límite de velocidad

🐛 Solución de problemas

Problemas de conexión

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

• Verifica que N8N_BASE_URL sea correcta 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 mejores prácticas

1. Empieza con plantillas: Usa plantillas predefinidas como punto de partida

2. Usa etiquetas: Organiza los flujos de trabajo con etiquetas para una gestión fácil

3. Supervisa las ejecuciones: Comprueba regularmente las ejecuciones fallidas

4. Limpieza: Elimina datos de ejecuciones antiguas 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

• Problemas: Issues de GitHub

• Discusiones: Discusiones de GitHub

• Comunidad de n8n: community.n8n.io

⬆ Volver al inicio