n8n Workflow Builder

Un servidor MCP para gestionar flujos de trabajo de n8n a través de su API.

Documentación

Servidor MCP n8n Workflow Builder

Automatización de flujos de trabajo impulsada por IA mediante lenguaje natural

Crea, gestiona y monitorea flujos de trabajo de n8n usando Claude AI y Cursor IDE a través del Model Context Protocol

Características • Inicio rápido • Documentación • Ejemplos • Referencia de API

AI-Powered Workflow Builder - Build n8n workflows with natural language

🎯 ¿Qué es esto?

n8n Workflow Builder MCP Server transforma la automatización de flujos de trabajo al permitirte crear y gestionar flujos de trabajo de n8n mediante IA conversacional. Se acabó la edición manual de JSON o la navegación compleja por la interfaz: solo describe lo que necesitas en lenguaje natural y deja que la IA lo construya por ti.

El problema que resuelve

❌ La creación manual de flujos de trabajo consume tiempo y es propensa a errores
❌ La edición compleja de JSON requiere conocimientos técnicos profundos
❌ Cambiar entre el IDE y la interfaz de n8n interrumpe tu flujo de desarrollo
❌ Gestionar múltiples entornos de n8n (dev, staging, prod) es tedioso

La solución

✅ Crea flujos de trabajo conversacionalmente usando Claude AI o Cursor IDE
✅ Interfaz de lenguaje natural: describe flujos de trabajo en lenguaje sencillo
✅ Compatibilidad multi-instancia: gestiona dev, staging y producción desde un solo lugar
✅ 17 herramientas potentes: gestión completa del ciclo de vida de flujos de trabajo
✅ Mantente en tu IDE: sin necesidad de cambiar de contexto

✨ Características principales

🤖 Creación de flujos de trabajo impulsada por IA

Crea flujos de trabajo complejos de n8n simplemente describiendo lo que necesitas. Claude AI y Cursor IDE entienden tu intención y generan flujos de trabajo listos para producción.

🌍 Gestión multi-instancia

Gestiona múltiples entornos de n8n (producción, staging, desarrollo) desde un solo servidor MCP con enrutamiento inteligente de instancias.

🛠️ 17 herramientas integrales

Cobertura completa del ciclo de vida del flujo de trabajo:

8 herramientas de flujo de trabajo: crear, actualizar, eliminar, activar, ejecutar
4 herramientas de ejecución: monitorear, reintentar, analizar ejecuciones
5 herramientas de etiquetas: organizar y categorizar flujos de trabajo
6 herramientas de credenciales (Epic 2): gestión segura de credenciales

💬 Interfaz de lenguaje natural

No se requiere edición de JSON. Construye flujos de trabajo así:

"Crea un flujo de trabajo de webhook que valide correos electrónicos de clientes, envíe una notificación de Slack y almacene datos en PostgreSQL"

🔒 Seguro por diseño

Protección integrada de credenciales
Cifrado de claves de API
Configuración segura multi-instancia
Nunca expone datos sensibles en registros

📚 Documentación integral

Más de 38 páginas de documentación con guías y tutoriales
Ejemplos interactivos y patrones de flujos de trabajo
Guías de solución de problemas y preguntas frecuentes
Referencia de API con documentación completa de herramientas

🚀 Inicio rápido

Requisitos previos

Node.js v14+ (se recomienda v18+)
npm v7+
Instancia de n8n con acceso a API (probado con n8n v1.82.3+)
Claude Desktop o Cursor IDE

Instalación

# Install globally via npm
npm install -g @kernel.salacoste/n8n-workflow-builder

# Verify installation
npx @kernel.salacoste/n8n-workflow-builder --version

Configuración

Opción 1: Multi-instancia (recomendada)

Crea .config.json en la raíz de tu proyecto:

{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "your_production_api_key"
    },
    "staging": {
      "n8n_host": "https://staging.n8n.example.com",
      "n8n_api_key": "your_staging_api_key"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "your_dev_api_key"
    }
  },
  "defaultEnv": "development"
}

Opción 2: Instancia única (compatible con versiones anteriores)

Crea el archivo .env:

N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key

Integración con Claude Desktop

Agrega a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

Reinicia Claude Desktop y ¡listo! 🎉

Integración con Cursor IDE

Agrega a .cursor/mcp.json en tu espacio de trabajo:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

📖 Documentación completa

Explora nuestro sitio de documentación integral:

🌐 Documentación completa

Enlaces rápidos

Sección	Descripción
🚀 Tutorial de inicio rápido	Crea tu primer flujo de trabajo en 5 minutos
📦 Guía de instalación	Instrucciones detalladas de configuración
🔧 Configuración	Configuración multi-instancia y de entornos
🛠️ Referencia de API	Documentación completa de herramientas
🏗️ Configuración multi-instancia	Gestiona múltiples entornos de n8n
💡 Patrones de uso	Mejores prácticas y patrones de conversación
🐛 Solución de problemas	Problemas comunes y soluciones

🎨 Ejemplos

Ejemplo 1: Crear un flujo de trabajo de webhook

Tú:

Crea un flujo de trabajo de webhook en staging que:

Reciba solicitudes POST en /customer-signup

Valide los campos de correo electrónico y nombre

Envíe un correo de bienvenida mediante Gmail

Almacene al cliente en PostgreSQL

Claude: ✅ Crea el flujo de trabajo completo con nodos de validación, correo electrónico y base de datos

Ejemplo 2: Gestión de flujos de trabajo multi-instancia

Tú:

Lista todos los flujos de trabajo activos en producción que no se hayan ejecutado en los últimos 7 días

Claude: 📊 Analiza el entorno de producción e identifica flujos de trabajo inactivos

Ejemplo 3: Depurar ejecuciones fallidas

Tú:

Depura el flujo de trabajo 456 en producción: está fallando con errores

Claude: 🔍 Recupera el historial de ejecuciones, identifica la causa raíz y sugiere correcciones

Ejemplo 4: Gestión de credenciales

Tú:

Muéstrame el esquema de credenciales OAuth2 y luego ayúdame a crear credenciales para la API de Google Sheets

Claude: 🔐 Recupera el esquema de credenciales y te guía en la creación segura de credenciales

🛠️ Referencia de herramientas MCP

Gestión de flujos de trabajo (8 herramientas)

Herramienta	Descripción	Ejemplo de uso
`list_workflows`	Lista todos los flujos de trabajo con filtros	"Muéstrame los flujos de trabajo activos en producción"
`get_workflow`	Recupera detalles completos del flujo de trabajo	"Obtén el flujo de trabajo 123 de staging"
`create_workflow`	Construye nuevos flujos de trabajo desde cero	"Crea un flujo de trabajo de informe diario"
`update_workflow`	Modifica flujos de trabajo existentes	"Agrega manejo de errores al flujo de trabajo 456"
`delete_workflow`	Elimina flujos de trabajo	"Elimina el flujo de trabajo 789"
`activate_workflow`	Habilita la ejecución del flujo de trabajo	"Activa el flujo de trabajo 123"
`deactivate_workflow`	Deshabilita la ejecución del flujo de trabajo	"Desactiva el flujo de trabajo 456"
`execute_workflow`	Ejecuta manualmente los flujos de trabajo	"Ejecuta el flujo de trabajo 789 con datos de prueba"

Gestión de ejecuciones (4 herramientas)

Herramienta	Descripción	Ejemplo de uso
`list_executions`	Visualiza el historial de ejecuciones con filtros	"Muéstrame las ejecuciones fallidas de hoy"
`get_execution`	Información detallada de ejecuciones	"Obtén detalles de la ejecución 9876"
`delete_execution`	Elimina registros de ejecución	"Elimina ejecuciones de prueba antiguas"
`retry_execution`	Reintenta ejecuciones de flujos de trabajo fallidas	"Reintenta la ejecución 9876"

Gestión de etiquetas (5 herramientas)

Herramienta	Descripción	Ejemplo de uso
`list_tags` / `get_tags`	Recupera todas las etiquetas de flujos de trabajo	"Muestra todas las etiquetas de flujos de trabajo"
`get_tag`	Obtiene información de una etiqueta específica	"Obtén detalles de la etiqueta 'email-automation'"
`create_tag`	Crea etiquetas de organización de flujos de trabajo	"Crea la etiqueta 'customer-workflows'"
`update_tag`	Modifica información de etiquetas	"Renombra la etiqueta a 'legacy-workflows'"
`delete_tag`	Elimina etiquetas de flujos de trabajo	"Elimina la etiqueta 'deprecated'"

Gestión de credenciales (6 herramientas - Epic 2)

Herramienta	Descripción	Ejemplo de uso
`get_credential_schema`	Obtiene el esquema JSON del tipo de credencial	"Muestra el esquema de httpBasicAuth"
`list_credentials`	Guía de seguridad (bloqueada por la API de n8n)	"Lista la guía de credenciales"
`get_credential`	Guía de seguridad (bloqueada por la API de n8n)	"Obtén la guía de credenciales"
`create_credential`	Crea credenciales con validación de esquema	"Crea credenciales OAuth2 de Gmail"
`update_credential`	Guía de inmutabilidad (DELETE + CREATE)	"Actualiza la guía de credenciales"
`delete_credential`	Elimina credenciales permanentemente	"Elimina la credencial 123"

🏗️ Arquitectura multi-instancia

Gestiona múltiples entornos de n8n con enrutamiento inteligente:

┌─────────────────────────────────────┐
│   MCP Server (Single Instance)     │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐  ┌──────────┐       │
│  │ ConfigLoader│ EnvironmentMgr   │
│  └──────────┘  └──────────┘       │
│         │            │             │
│         ▼            ▼             │
│  ┌─────────────────────────┐      │
│  │   Instance Routing      │      │
│  └─────────────────────────┘      │
│         │                          │
└─────────┼──────────────────────────┘
          │
    ┌─────┴─────┬─────────────┬──────────────┐
    │           │             │              │
    ▼           ▼             ▼              ▼
┌────────┐  ┌────────┐   ┌────────┐    ┌────────┐
│  Dev   │  │Staging │   │  Prod  │    │Custom  │
│ n8n    │  │  n8n   │   │  n8n   │    │  n8n   │
└────────┘  └────────┘   └────────┘    └────────┘

Beneficios:

✅ Un solo servidor MCP gestiona todos los entornos
✅ Enrutamiento automático de instancias según el contexto
✅ Claves de API separadas por entorno
✅ Cambio fácil de entorno en las conversaciones

🎯 Casos de uso

🚀 Flujo de trabajo de desarrollo

Desarrolla en el entorno de desarrollo: crea y prueba flujos de trabajo localmente
Despliega a staging: valida en el entorno de QA
Promueve a producción: despliega con confianza

📊 Operaciones y monitoreo

Monitorea el estado de ejecución en todos los entornos
Depura flujos de trabajo fallidos con análisis detallado
Realiza seguimiento del rendimiento y la fiabilidad de los flujos de trabajo

🔄 Migración de flujos de trabajo

Exporta flujos de trabajo de una instancia
Importa a otra con adaptación automática
Operaciones masivas en todos los entornos

📝 Documentación y aprendizaje

Genera documentación de flujos de trabajo automáticamente
Aprende patrones de n8n con la guía de IA
Explora ejemplos y plantillas de flujos de trabajo

🔒 Seguridad y mejores prácticas

Protección de credenciales

✅ .config.json excluido automáticamente de git mediante .gitignore
✅ Las claves de API nunca se registran (solo se muestran los primeros 20 caracteres)
✅ Las credenciales se cifran mediante la API de n8n
✅ Sin datos sensibles en paquetes npm

Seguridad multi-instancia

✅ Claves de API separadas por entorno
✅ Las claves de producción se aíslan del desarrollo
✅ Validación de instancia antes de las llamadas a la API

Operaciones seguras

⚠️ IMPORTANT: Be careful with destructive operations!

- Always test in development first
- Use get_workflow to backup before modifications
- Review workflow details before deletion
- Enable debug mode for troubleshooting

🐛 Solución de problemas

Problemas comunes

Falla la conexión del servidor MCP

Síntomas: Claude/Cursor no encuentra las herramientas de n8n

Soluciones:

Reinicia Claude Desktop / Cursor IDE
Verifica la sintaxis de claude_desktop_config.json / .cursor/mcp.json
Confirma que la instancia de n8n sea accesible
Habilita el modo de depuración: DEBUG=true en el entorno

Guía completa de depuración

Errores 404 al llamar a la API de n8n

Síntomas: "Request failed with status code 404"

Soluciones:

Verifica que n8n_host use la URL base (por ejemplo, https://n8n.example.com)
NO incluyas el sufijo /api/v1 (el servidor lo agrega automáticamente)
Comprueba que la clave de API de n8n tenga los permisos correctos
Prueba la conectividad: curl https://your-n8n-instance.com/api/v1/workflows

Guía de configuración

Falla la activación del flujo de trabajo

Síntomas: "Workflow cannot be activated without valid trigger"

Soluciones:

Asegúrate de que el flujo de trabajo tenga al menos un nodo de activación (webhook, programación, etc.)
manualTrigger NO es reconocido por la API de n8n v1.82.3
El servidor agrega automáticamente activadores válidos si faltan

Referencia de errores

Obtener ayuda

📚 Guía completa de solución de problemas
🐛 Reportar problemas
💬 Debates de GitHub

📊 Novedades

Versión 0.9.3 (última): seguridad y documentación

🔒 Corrección de seguridad: se evitó que los archivos de registro se publicaran en npm
📦 Optimización del paquete: tamaño reducido a 653KB (desde 699KB)
📚 Mejora de documentación: se agregaron insignias y se mejoraron los metadatos de npm
✅ Rotación de claves de API: prácticas de seguridad actualizadas

Versión 0.9.0: cumplimiento del protocolo MCP

✅ Compatibilidad total con controladores de notificaciones MCP
✅ Corregido el error "Method 'notifications/initialized' not found"
📦 Optimización del tamaño del paquete: 1.3MB → 278KB
🏗️ Arquitectura multi-instancia con enrutamiento inteligente
🔐 Gestión mejorada de credenciales con validación de esquema

Epic 2 completa (13/13 historias): implementación avanzada de API

✅ 17 herramientas MCP implementadas (8 flujos de trabajo + 4 ejecuciones + 5 etiquetas + 6 credenciales)
✅ 100% de tasa de éxito en pruebas en todas las implementaciones
✅ Más de 12,000 líneas de documentación con ejemplos completos
✅ Calidad lista para producción con cero errores

Ver registro de cambios completo

🗺️ Hoja de ruta

✅ Completado

Operaciones CRUD básicas de flujos de trabajo
Gestión y monitoreo de ejecuciones
Organización de flujos de trabajo basada en etiquetas
Arquitectura multi-instancia
Gestión del ciclo de vida de credenciales
Sitio de documentación completo (más de 38 páginas)
Despliegue en GitHub Pages con CI/CD

🚧 En progreso

Biblioteca de plantillas de flujos de trabajo
Patrones mejorados de recuperación de errores
Optimización de rendimiento para flujos de trabajo grandes
Capacidades avanzadas de filtrado y búsqueda

🔮 Planificado

Integración de editor visual de flujos de trabajo
Control de versiones y reversión de flujos de trabajo
Desarrollo colaborativo de flujos de trabajo
Analíticas avanzadas e información
Mercado de flujos de trabajo y uso compartido

Sugerir una función

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como puedes ayudar:

Formas de contribuir

🐛 Reportar errores: Crear un issue
💡 Sugerir funciones: Abrir una discusión
📖 Mejorar la documentación: Envía mejoras de documentación
🔧 Enviar pull requests: Corrige errores o agrega funciones

Configuración de desarrollo

# Clone repository
git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git
cd mcp-n8n-workflow-builder

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run dev