n8n-MCP (Fork de Producción)

Servidor MCP (Model Context Protocol) para n8n — fork de czlonkowski/n8n-mcp con modificaciones para despliegue en producción sobre Contabo VPS.

Este servidor actúa como puente entre n8n y asistentes de IA (Claude, Hermes Agent, etc.), proporcionando acceso estructurado a la documentación de nodos, propiedades, operaciones y plantillas de n8n.

📋 Tabla de Contenidos

• Características

• Requisitos

• Despliegue con Docker Compose

• Variables de Entorno

• Conexión a la Instancia n8n

• Conexión a Hermes Agent Gateway

• Actualizar desde Upstream

• Estructura del Proyecto

• Seguridad

• Licencia

Related MCP server: n8n-MCP

Características

• 🔌 Servidor MCP completo — expone herramientas para buscar, validar y gestionar workflows de n8n

• 📚 Documentación de nodos — acceso a 1,845+ nodos (816 core + 1,029 community)

• 🐳 Dockerizado — despliegue con un solo comando usando Docker Compose

• 🔐 Autenticación por token — protegido con AUTH_TOKEN

• 🌐 Modo HTTP — compatible con cualquier cliente MCP que soporte SSE (Server-Sent Events)

• 🏗️ Multi-tenant opcional — soporte para múltiples instancias n8n

• 📊 Telemetría anónima desactivada por defecto en este fork

Requisitos

• Docker y Docker Compose instalados

• Una instancia de n8n corriendo (local o remota)

• (Opcional) API Key de n8n para herramientas de gestión de workflows

Despliegue con Docker Compose

1. Clonar el repositorio

git clone <url-de-este-repo> n8n-mcp
cd n8n-mcp

2. Configurar variables de entorno

Copia el archivo de ejemplo y edita las variables:

cp .env.example .env

Edita .env con tus valores reales. Las variables mínimas requeridas son:

AUTH_TOKEN=*** 3. Construir y levantar

```bash
docker compose up -d --build

El servidor estará disponible en http://localhost:3001 (mapeado a 127.0.0.1:3001 por seguridad).

4. Verificar el despliegue

curl http://localhost:3001/health
# Respuesta esperada: {"status":"ok"}

Red Docker

El servicio se conecta a la red baota_net (externa), que debe existir previamente. Esta es la misma red donde corre n8n, permitiendo comunicación interna via http://n8n:5678.

Si tu configuración de red es diferente, edita la sección networks en docker-compose.yml.

Variables de Entorno

Configuración General

Autenticación y Seguridad

Conexión a n8n

Telemetría

Multi-Tenant (Opcional)

Conexión a la Instancia n8n

1. Obtener API Key de n8n

1. Ve a tu instancia n8n → Settings → API

2. Crea una nueva API Key

3. Copia la key generada

2. Configurar en .env

N8N_API_URL=http://n8n:5678
N8N_API_KEY=*** **Nota:** Si n8n corre en el mismo Docker network (`baota_net`), usa el nombre del contenedor (`n8n`) como hostname. Si está en otro servidor, usa la URL completa.

### 3. Verificar conectividad

```bash
curl -H "Authorization: Bearer *** http://localhost:3001/health

Conexión a Hermes Agent Gateway

Para conectar este servidor MCP a Hermes Agent (by Nous Research):

1. Asegurar que el servidor está corriendo

docker compose ps
# n8n-mcp debe estar "Up"

2. Configurar en Hermes Agent

En la configuración de Hermes Agent, agrega un nuevo servidor MCP:

{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "https://tu-dominio.com/mcp",
      "headers": {
        "Authorization": "Bearer <AUTH_TOKEN>"
      }
    }
  }
}

O si estás en la misma red local:

{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "Bearer <AUTH_TOKEN>"
      }
    }
  }
}

3. Verificar la conexión

Hermes Agent debería detectar automáticamente las herramientas disponibles. Puedes verificar preguntando:

"¿Qué herramientas de n8n tienes disponibles?"

Actualizar desde Upstream

Este repositorio es un fork de czlonkowski/n8n-mcp. Para actualizar con los últimos cambios:

1. Agregar el remote upstream (solo la primera vez)

git remote add upstream https://github.com/czlonkowski/n8n-mcp.git

2. Fetch y merge

git fetch upstream
git checkout main
git merge upstream/main

3. Resolver conflictos

Si hay conflictos (especialmente en docker-compose.yml, .env.example, o .gitignore), resuélvelos manualmente preservando las configuraciones locales de producción.

4. Reconstruir y desplegar

docker compose down
docker compose up -d --build

5. Verificar

docker compose logs -f n8n-mcp
curl http://localhost:3001/health

Estructura del Proyecto

n8n-mcp/
├── src/
│   ├── mcp/              # Servidor MCP y herramientas
│   ├── services/         # Validación, templates, ejemplos
│   ├── database/         # Capa de acceso a datos (SQLite)
│   ├── telemetry/        # Sistema de telemetría (desactivado)
│   └── utils/            # Utilidades
├── data/
│   ├── skills/           # Documentación de habilidades para IA
│   └── nodes.db          # Base de datos de nodos (generada)
├── scripts/              # Scripts de utilidad y testing
├── tests/                # Tests unitarios e integración
├── docker/               # Archivos de configuración Docker
├── docker-compose.yml    # Configuración de despliegue
├── Dockerfile            # Build multi-etapa optimizado
├── .env.example          # Plantilla de variables de entorno
└── package.json          # Dependencias y scripts

Seguridad

Buenas prácticas

1. NUNCA subas el archivo .env al repositorio — está en .gitignore

2. Usa AUTH_TOKEN fuerte (generar con: openssl rand -base64 32)

3. El puerto está mapeado a 127.0.0.1:3001 — solo accesible localmente

4. Usa un proxy inverso (Nginx/Traefik) con HTTPS para exponerlo públicamente

5. La telemetría está desactivada por defecto (N8N_MCP_TELEMETRY_DISABLED=true)

6. El modo SSRF está en permissive para comunicación interna — ajustar según necesidades

Verificación de secretos

Este repositorio ha sido auditado para garantizar que no contiene:

• API keys reales

• Tokens JWT completos

• Credenciales de Supabase

• Contraseñas o secrets de producción

Todos los valores en archivos de test son placeholders truncados (ej: eyJhbG...nkCk, test123...890).

Licencia

MIT — ver archivo LICENSE.

Basado en czlonkowski/n8n-mcp por Romuald Czlonkowski.