n8n MCP Server

Un servidor MCP para interactuar con flujos de trabajo de n8n mediante lenguaje natural.

Documentación

n8n MCP Server

Un servidor de Model Context Protocol (MCP) que permite a los asistentes de IA interactuar con flujos de trabajo de n8n mediante lenguaje natural.

Descripción general

Este proyecto proporciona un servidor de Model Context Protocol (MCP) que permite a los asistentes de IA interactuar sin problemas con n8n, una popular herramienta de automatización de flujos de trabajo. Actúa como un puente, permitiendo a los asistentes de IA gestionar y controlar programáticamente flujos de trabajo y ejecuciones de n8n mediante comandos en lenguaje natural.

Instalación

Requisitos previos

Node.js 20 o posterior
Instancia de n8n con acceso a la API habilitado

Instalar desde npm

npm install -g @leonardsellem/n8n-mcp-server

Instalar desde el código fuente

# Clone the repository
git clone https://github.com/leonardsellem/n8n-mcp-server.git
cd n8n-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Install globally
npm install -g .

Instalación con Docker

También puedes ejecutar el servidor usando Docker:

# Pull the image
docker pull leonardsellem/n8n-mcp-server

# Run the container with your n8n API configuration
docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  -e N8N_API_KEY=your_n8n_api_key \
  -e N8N_WEBHOOK_USERNAME=username \
  -e N8N_WEBHOOK_PASSWORD=password \
  leonardsellem/n8n-mcp-server

Actualización del servidor

La forma de actualizar el servidor depende de cómo lo hayas instalado inicialmente.

1. Instalado globalmente mediante npm

Si instalaste el servidor usando npm install -g @leonardsellem/n8n-mcp-server:

Abre tu terminal o símbolo del sistema.
Ejecuta el siguiente comando para obtener la última versión:
```
npm install -g @leonardsellem/n8n-mcp-server@latest
```
Si el servidor está actualmente en ejecución (por ejemplo, como proceso en segundo plano o servicio), deberás reiniciarlo para que los cambios surtan efecto.

2. Instalado desde el código fuente

Si clonaste el repositorio e instalaste desde el código fuente:

Abre tu terminal o símbolo del sistema.
Navega al directorio donde clonaste el proyecto:
```
cd path/to/n8n-mcp-server
```
Si has realizado cambios locales en el código que deseas conservar, considera guardarlos temporalmente (opcional):
```
git stash
```
Puedes aplicarlos más tarde con git stash pop.
Obtén los últimos cambios del repositorio (asumiendo que estás en la rama main):
```
git pull origin main
```
Si estás en una rama diferente, reemplaza main con el nombre de tu rama.
Instala o actualiza las dependencias modificadas:
```
npm install
```
Reconstruye el proyecto para incluir las últimas actualizaciones:
```
npm run build
```
Si anteriormente lo instalaste globalmente desde esta carpeta de código fuente usando npm install -g ., es posible que quieras ejecutar este comando nuevamente para actualizar el enlace global:
```
npm install -g .
```
Reinicia el servidor.
- Si ejecutas el servidor directamente usando un comando como node build/index.js en la configuración MCP de tu asistente de IA, asegúrate de que la ruta siga siendo correcta. Usar npm install -g . y luego n8n-mcp-server como comando debería mantener esto consistente.

3. Usando Docker

Si estás ejecutando el servidor usando Docker:

Obtén la última imagen de Docker Hub:

docker pull leonardsellem/n8n-mcp-server:latest

Detén y elimina tu contenedor anterior. Necesitarás el nombre o ID de tu contenedor (puedes encontrarlo usando docker ps):
```
docker stop <your_container_name_or_id>
docker rm <your_container_name_or_id>
```
Inicia un nuevo contenedor con la imagen actualizada. Usa el mismo comando docker run que usaste anteriormente, incluyendo todas tus variables de entorno necesarias (consulta la sección "Instalación con Docker" para ver un comando de ejemplo). Por ejemplo:
```
docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \
  -e N8N_API_KEY=your_n8n_api_key \
  -e N8N_WEBHOOK_USERNAME=username \
  -e N8N_WEBHOOK_PASSWORD=password \
  leonardsellem/n8n-mcp-server:latest
```
Asegúrate de usar :latest o la etiqueta de versión específica que deseas ejecutar.

Configuración

Crea un archivo .env en el directorio donde ejecutarás el servidor, usando .env.example como plantilla:

cp .env.example .env

Configura las siguientes variables de entorno:

Variable	Descripción	Ejemplo
`N8N_API_URL`	URL completa de la API de n8n, incluyendo `/api/v1`	`http://localhost:5678/api/v1`
`N8N_API_KEY`	Clave de API para autenticarse con n8n	`n8n_api_...`
`N8N_WEBHOOK_USERNAME`	Nombre de usuario para la autenticación de webhooks (si se usan webhooks)	`username`
`N8N_WEBHOOK_PASSWORD`	Contraseña para la autenticación de webhooks	`password`
`DEBUG`	Habilitar registro de depuración (opcional)	`true` o `false`

Generación de una clave de API de n8n

Abre tu instancia de n8n en un navegador
Ve a Configuración > API > Claves de API
Crea una nueva clave de API con los permisos adecuados
Copia la clave en tu archivo .env

Uso

Ejecución del servidor

Desde el directorio de instalación:

n8n-mcp-server

O si se instaló globalmente:

n8n-mcp-server

Integración con asistentes de IA

Después de compilar el servidor (npm run build), debes configurar tu asistente de IA (como VS Code con la extensión de Claude o la aplicación Claude Desktop) para ejecutarlo. Esto generalmente implica editar un archivo de configuración JSON.

Configuración de ejemplo (p. ej., en VS Code settings.json o Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    // Give your server a unique name
    "n8n-local": {
      // Use 'node' to execute the built JavaScript file
      "command": "node",
      // Provide the *absolute path* to the built index.js file
      "args": [
        "/path/to/your/cloned/n8n-mcp-server/build/index.js"
        // On Windows, use double backslashes:
        // "C:\\path\\to\\your\\cloned\\n8n-mcp-server\\build\\index.js"
      ],
      // Environment variables needed by the server
      "env": {
        "N8N_API_URL": "http://your-n8n-instance:5678/api/v1", // Replace with your n8n URL
        "N8N_API_KEY": "YOUR_N8N_API_KEY", // Replace with your key
        // Add webhook credentials only if you plan to use webhook tools
        // "N8N_WEBHOOK_USERNAME": "your_webhook_user",
        // "N8N_WEBHOOK_PASSWORD": "your_webhook_password"
      },
      // Ensure the server is enabled
      "disabled": false,
      // Default autoApprove settings
      "autoApprove": []
    }
    // ... other servers might be configured here
  }
}

Puntos clave:

Reemplaza /path/to/your/cloned/n8n-mcp-server/ con la ruta absoluta real donde clonaste y compilaste el repositorio.
Usa el separador de ruta correcto para tu sistema operativo (barras diagonales / para macOS/Linux, dobles barras invertidas \\ para Windows).
Asegúrate de proporcionar el N8N_API_URL correcto (incluyendo /api/v1) y N8N_API_KEY.
El servidor debe compilarse (npm run build) antes de que el asistente pueda ejecutar el archivo build/index.js.

Herramientas disponibles

El servidor proporciona las siguientes herramientas:

Uso de webhooks

Este servidor MCP admite la ejecución de flujos de trabajo mediante webhooks de n8n. Para usar esta funcionalidad:

Crea un flujo de trabajo activado por webhook en n8n.
Configura la autenticación básica en tu nodo de webhook.
Usa la herramienta run_webhook para activar el flujo de trabajo, pasando solo el nombre del flujo de trabajo.

Ejemplo:

const result = await useRunWebhook({
  workflowName: "hello-world", // Will call <n8n-url>/webhook/hello-world
  data: {
    prompt: "Hello from AI assistant!"
  }
});

La autenticación del webhook se gestiona automáticamente usando las variables de entorno N8N_WEBHOOK_USERNAME y N8N_WEBHOOK_PASSWORD.

Gestión de flujos de trabajo

workflow_list: Listar todos los flujos de trabajo
workflow_get: Obtener detalles de un flujo de trabajo específico
workflow_create: Crear un nuevo flujo de trabajo
workflow_update: Actualizar un flujo de trabajo existente
workflow_delete: Eliminar un flujo de trabajo
workflow_activate: Activar un flujo de trabajo
workflow_deactivate: Desactivar un flujo de trabajo

Gestión de ejecuciones

execution_run: Ejecutar un flujo de trabajo mediante la API
run_webhook: Ejecutar un flujo de trabajo mediante un webhook
execution_get: Obtener detalles de una ejecución específica
execution_list: Listar ejecuciones de un flujo de trabajo
execution_stop: Detener una ejecución en curso

Recursos

El servidor proporciona los siguientes recursos:

n8n://workflows/list: Lista de todos los flujos de trabajo
n8n://workflow/{id}: Detalles de un flujo de trabajo específico
n8n://executions/{workflowId}: Lista de ejecuciones de un flujo de trabajo
n8n://execution/{id}: Detalles de una ejecución específica

Hoja de ruta

El n8n MCP Server es un proyecto impulsado por la comunidad, ¡y su dirección futura estará determinada por tus comentarios y contribuciones!

Actualmente, nuestra hoja de ruta es flexible y está en desarrollo continuo. Creemos en evolucionar el servidor según las necesidades e ideas de nuestros usuarios.

Te animamos a participar en la configuración del futuro de esta herramienta:

Sugerir funciones: ¿Tienes una idea para una nueva herramienta, recurso o mejora?
Discutir prioridades: ¿Quieres opinar sobre en qué deberíamos centrarnos a continuación?

Comparte tus opiniones, solicitudes de funciones e ideas abriendo un issue en nuestra página de GitHub Issues. ¡Construyamos juntos una herramienta potente para asistentes de IA!

Desarrollo

Compilación

npm run build

Ejecución en modo de desarrollo

npm run dev

Pruebas

npm test

Linting

npm run lint

Contribuciones

Damos la bienvenida a las contribuciones de la comunidad y estamos emocionados de ver cómo puedes ayudar a mejorar el n8n MCP Server. Ya sea corrigiendo un error, proponiendo una nueva función o mejorando la documentación, tu ayuda es valiosa.

Informe de errores

Si encuentras un error, repórtalo abriendo un issue en nuestra página de GitHub Issues.

Al enviar un informe de error, incluye lo siguiente:

Un título claro y descriptivo.
Una descripción detallada del problema, incluyendo los pasos para reproducir el error.
Información sobre tu entorno (p. ej., versión de Node.js, versión del n8n MCP Server, sistema operativo).
Cualquier mensaje de error o captura de pantalla relevante.

Sugerencia de mejoras

Siempre estamos buscando formas de mejorar el servidor. Si tienes una idea para una mejora o una nueva función, abre un issue en nuestra página de GitHub Issues.

Proporciona:

Un título claro y descriptivo para tu sugerencia.
Una explicación detallada de la mejora propuesta y por qué sería beneficiosa.
Cualquier caso de uso o ejemplo potencial.

Envío de pull requests

Si deseas contribuir con código, sigue estos pasos:

Haz un fork del repositorio: Crea tu propio fork del repositorio n8n-mcp-server.
Crea una rama: Crea una nueva rama en tu fork para tus cambios (p. ej., git checkout -b feature/your-feature-name o bugfix/issue-number).
Realiza tus cambios: Implementa tu función o corrección de errores.
- Asegúrate de que tu código cumpla con el estilo de codificación existente. (Usamos Prettier para el formato, que se puede ejecutar con npm run lint).
- Incluye pruebas para tus cambios si corresponde. Puedes ejecutar las pruebas usando npm test.
Haz commit de tus cambios: Escribe mensajes de commit claros y concisos.
Haz push a tu fork: Sube tus cambios a tu repositorio bifurcado.
Abre un Pull Request (PR): Envía un PR a la rama main del repositorio oficial n8n-mcp-server.
- Proporciona un título y una descripción claros para tu PR, explicando los cambios que has realizado y haciendo referencia a cualquier issue relacionado.

Revisaremos tu PR lo antes posible y proporcionaremos comentarios. ¡Gracias por tu contribución!

Licencia

MIT

🚀 ¡Únete a nuestro equipo: Convocatoria de co-mantenedores!

Este proyecto es una herramienta vibrante impulsada por la comunidad, utilizada activamente por entusiastas de la IA y desarrolladores. Actualmente, se mantiene a tiempo parcial por una persona apasionada que no es una ingeniera experimentada, pero está dedicada a unir la IA con la automatización de flujos de trabajo. Para ayudar a que este proyecto florezca, garantizar su salud a largo plazo y mantener el ritmo de su creciente base de usuarios, ¡buscamos co-mantenedores entusiastas para unirse al equipo!

¿Por qué contribuir?

Aprende y crece: Perfecciona tus habilidades en áreas como TypeScript, Node.js, integración de API y desarrollo de herramientas de IA.
Colabora: Trabaja junto a otros desarrolladores y usuarios de IA motivados.
Genera un impacto: Da forma directamente al futuro de este proyecto y ayuda a construir una herramienta valiosa para la comunidad de IA.
Código abierto: Gana experiencia contribuyendo a un proyecto de código abierto.

Cómo puedes ayudar

¡Damos la bienvenida a contribuciones en muchas formas! Aquí hay algunas áreas donde podrías marcar una gran diferencia:

Corrección de errores: Ayúdanos a identificar y eliminar errores para mejorar la estabilidad.
Desarrollo de funciones: Implementa nuevas herramientas y funcionalidades según las necesidades de los usuarios y tus ideas.
Documentación: Mejora nuestras guías, ejemplos y referencias de API para hacer el proyecto más accesible.
Pruebas: Mejora nuestro conjunto de pruebas (unitarias, de integración) para garantizar la calidad y fiabilidad del código.
CI/CD: Ayuda a optimizar nuestros pipelines de desarrollo e implementación.
Revisiones de código: Proporciona comentarios sobre pull requests y ayuda a mantener los estándares de código.
Soporte comunitario: Ayuda a los usuarios con preguntas y gestiona discusiones.

¡Participa!

Si te entusiasma la intersección entre la IA y la automatización de flujos de trabajo, y buscas una oportunidad gratificante en código abierto, ¡nos encantaría saber de ti!

¿Listo para contribuir?

Consulta nuestra página de GitHub Issues para encontrar tareas existentes, sugerir nuevas ideas o expresar tu interés en convertirte en co-mantenedor.
Puedes abrir un issue titulado "Co-maintainer Application" para postularte formalmente, o simplemente comenzar a contribuir a los issues existentes.
Alternativamente, no dudes en contactar a los mantenedores existentes si tienes preguntas.

¡Construyamos juntos el futuro de la automatización de flujos de trabajo impulsada por IA! 🙌

¡Gracias a la comunidad por el apoyo!