n8n

Proporciona a los asistentes de IA acceso directo a la plataforma de automatización n8n.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Servidor MCP de n8n

Un servidor de Protocolo de Contexto de Modelo (MCP) integral que brinda a los asistentes de IA acceso directo a tu plataforma de automatización n8n. Este servidor permite una integración perfecta entre herramientas de IA (como Claude Desktop) y los flujos de trabajo, variables, credenciales y ejecuciones de n8n.

🚀 Características

Integración completa de n8n (18 herramientas)

  • Gestión de flujos de trabajo (7 herramientas)

    • list_workflows - Listar todos los flujos de trabajo
    • get_workflow - Obtener detalles del flujo de trabajo por ID
    • create_workflow - Crear nuevos flujos de trabajo
    • update_workflow - Actualizar flujos de trabajo existentes
    • delete_workflow - Eliminar flujos de trabajo
    • activate_workflow - Activar flujos de trabajo
    • deactivate_workflow - Desactivar flujos de trabajo

  • Gestión de variables (5 herramientas)

    • list_variables - Listar todas las variables
    • get_variable - Obtener variable por clave
    • create_variable - Crear nuevas variables
    • update_variable - Actualizar variables existentes
    • delete_variable - Eliminar variables

  • Gestión de credenciales (3 herramientas)

    • list_credentials - Listar todas las credenciales (saneadas)
    • create_credential - Crear nuevas credenciales
    • delete_credential - Eliminar credenciales

  • Gestión de ejecuciones (2 herramientas)

    • list_executions - Listar ejecuciones de flujos de trabajo
    • get_execution - Obtener detalles de ejecución por ID

  • Gestión del sistema (1 herramienta)

    • self_test - Probar conectividad y permisos del servidor

Arquitectura híbrida

  • Protocolo MCP: Cumplimiento total de JSON-RPC 2.0 mediante transporte stdio
  • Puente HTTP: Verificaciones de salud y endpoints de prueba
  • Detección automática: Cambia automáticamente entre modos

📦 Instalación

Requisitos previos

  • Node.js 18+
  • Instancia de n8n en ejecución y accesible
  • Clave API de n8n configurada

Configuración

  1. Clonar el repositorio

    git clone <repository-url>
cd n8n-mcp

  2. Instalar dependencias

    npm install

  3. Configurar el entorno

    cp .env.example .env
# Edit .env with your settings:
# N8N_API_KEY=your-api-key-here
# N8N_BASE_URL=http://localhost:5678
# MCP_PORT=3001

  4. Probar la instalación

    # Test HTTP endpoints
node index.js &
curl http://localhost:3001/health

# Test MCP protocol
node test-all-tools.js

🔧 Uso

Para clientes MCP (Claude Desktop, etc.)

El servidor se ejecuta como un servidor MCP basado en stdio para clientes de IA:

node index.js

Configuración de Claude Desktop (~/.claude_desktop_config.json):

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "/path/to/n8n-mcp",
      "env": {
        "N8N_API_KEY": "your-n8n-api-key-here",
        "N8N_BASE_URL": "http://localhost:5678"
      }
    }
  }
}

Para monitoreo HTTP

Cuando se ejecuta en una terminal (TTY), el servidor proporciona endpoints HTTP:

node index.js
# Server starts on http://localhost:3001

# Available endpoints:
# GET  /health - Health check
# POST /test   - Run self-test
# GET  /       - Usage instructions

Pruebas directas de MCP

Prueba el protocolo MCP directamente:

# Initialize connection
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node index.js

# Call a tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"self_test","arguments":{}}}' | node index.js

🧪 Pruebas

Suite de pruebas integral

Ejecuta la suite de pruebas completa para validar las 18 herramientas:

node test-all-tools.js

Esto:

  • Probará el cumplimiento del protocolo MCP
  • Validará todas las definiciones de herramientas
  • Comprobará la conectividad con la API de n8n
  • Verificará el manejo de errores
  • Proporcionará resultados detallados

Pruebas manuales

# Health check
curl http://localhost:3001/health

# Quick self-test
curl -POST http://localhost:3001/test

# Individual tool test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workflows","arguments":{"limit":5}}}' | node index.js

🔒 Seguridad

Gestión de claves API

  • Almacena las claves API en variables de entorno
  • Usa archivos .env para el desarrollo local
  • Nunca comprometas las claves API en el control de versiones

Saneamiento de credenciales

  • Los datos de credenciales se sanean automáticamente en las respuestas
  • Solo se exponen metadatos (ID, nombre, tipo)
  • Los datos sensibles de credenciales nunca se devuelven

Seguridad de red

  • El servidor HTTP se vincula a localhost por defecto
  • Cabeceras CORS configuradas para solicitudes entre orígenes
  • Sin datos sensibles expuestos a través de endpoints HTTP

🐛 Solución de problemas

Problemas comunes

1. "N8N_API_TOKEN no configurado"

# Solution: Set your API key
export N8N_API_KEY=your-api-key-here
# Or add to .env file

2. Errores de "Conexión rechazada"

# Solution: Check n8n is running
curl http://localhost:5678/api/v1/workflows?limit=1 -H "X-N8N-API-KEY: your-key"

3. "La licencia no permite la función: variables"

# This is expected for n8n Community Edition
# Variables require n8n Pro/Enterprise license
# The tool will still work but return license errors

4. "Método GET no permitido" para credenciales

# Some n8n configurations restrict credential access
# Check your n8n security settings

5. Puerto ya en uso (EADDRINUSE)

# Solution: Kill existing process or change port
pkill -f "node index.js"
# Or set different port: MCP_PORT=3002 node index.js

Modo de depuración

Habilita el registro detallado:

DEBUG=1 node index.js

Validar configuración

# Test n8n connectivity
curl -H "X-N8N-API-KEY: your-key" http://localhost:5678/api/v1/workflows?limit=1

# Test MCP server
node test-all-tools.js

📊 Monitoreo

Verificaciones de salud

# Basic health
curl http://localhost:3001/health

# Detailed system test
curl -X POST http://localhost:3001/test | jq '.result.summary'

Monitoreo de rendimiento

El servidor registra todas las ejecuciones de herramientas y proporciona información de tiempos:

  • Tiempo de ejecución de herramientas
  • Tiempo de respuesta de la API de n8n
  • Tasas y tipos de errores

🤝 Contribuciones

Configuración de desarrollo

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Ejecuta las pruebas: node test-all-tools.js
  5. Envía una solicitud de extracción

Añadir nuevas herramientas

  1. Añade la definición de la herramienta en setupToolHandlers()
  2. Implementa el método de la herramienta
  3. Añade el caso de prueba en test-all-tools.js
  4. Actualiza la documentación

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🔗 Proyectos relacionados

📞 Soporte

  • Problemas: Usa GitHub Issues para informes de errores
  • Discusiones: Usa GitHub Discussions para preguntas
  • Documentación: Consulta este README y los comentarios del código

¿Listo para automatizar con IA? 🤖✨

¡Tus flujos de trabajo de n8n ahora son accesibles para asistentes de IA a través del Protocolo de Contexto de Modelo!