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

---

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

Variable	Descripción	Valor por Defecto
MCP_MODE	Modo del servidor (stdio o http)	http
PORT	Puerto HTTP	3001
HOST	Host de escucha	0.0.0.0
NODE_ENV	Entorno (development / production)	production
LOG_LEVEL	Nivel de logging	info
NODE_DB_PATH	Ruta a la base de datos SQLite	/app/data/nodes.db
REBUILD_ON_START	Reconstruir BD al iniciar	false

Autenticación y Seguridad

Variable	Descripción	Requerido
AUTH_TOKEN	Token de autenticación para HTTP	Sí
BASE_URL	URL pública del servidor	No
WEBHOOK_SECURITY_MODE	Modo de protección SSRF (strict / moderate / permissive)	permissive
TRUST_PROXY	Confiar en proxy inverso (0 o 1)	0

Conexión a n8n

Variable	Descripción	Requerido
N8N_API_URL	URL de la instancia n8n (sin /api/v1)	Sí
N8N_API_KEY	API Key de n8n	Sí
N8N_API_TIMEOUT	Timeout de requests (ms)	30000
N8N_API_MAX_RETRIES	Reintentos máximos	3

Telemetría

Variable	Descripción	Valor por Defecto
N8N_MCP_TELEMETRY_DISABLED	Desactivar telemetría	true

Multi-Tenant (Opcional)

Variable	Descripción	Valor por Defecto
ENABLE_MULTI_TENANT	Activar modo multi-tenant	false
MULTI_TENANT_SESSION_STRATEGY	Estrategia de sesiones (instance / shared)	instance

---

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.