n8n Automation Kit

Kit completo para conectar Claude Code con n8n en proyectos reales. Incluye MCPs pre-configurados, skills especializadas, un subagente arquitecto de workflows, y templates listos para usar.

Creado por Carlos Domínguez — Imperio Digital · VibeCoding

---

Qué incluye

n8n-automation-kit/
├── .mcp.json                        ← Template de MCPs (editar con tus credenciales)
├── CLAUDE.md                        ← Cuestionario de contexto para Claude (rellenar)
├── MEMORY.md                        ← Sistema de autoaprendizaje (Claude lo actualiza solo)
├── skills/
│   ├── n8n-coolify-fullstack/       ← Skill exclusiva — instalar en ~/.claude/skills/
│   ├── make-to-n8n/                 ← Skill para migrar escenarios Make → n8n
│   └── n8n-sdk-rules/               ← Reglas canónicas del @n8n/workflow-sdk oficial
├── agents/
│   └── workflow-architect/          ← Subagente que diseña planes completos de workflows
├── docs/
│   ├── mcp-vs-api.md                ← Cuándo usar MCP vs API REST
│   └── setup-guide.md               ← Guía de instalación detallada
├── workflows/
│   ├── README.md                    ← Instrucciones para poner tus workflows aquí
│   └── starters/
│       └── webhook-router-starter.json  ← Workflow base con sticky notes incluidas
└── workshop/
    └── index.html                   ← Workshop guide interactivo de la clase

---

Inicio en 3 pasos

Paso 1 — Clonar y abrir en Claude Code

git clone https://github.com/Carlos-Dominguez-faber/n8n-automation-kit mi-proyecto-n8n
cd mi-proyecto-n8n
claude   # Abrir Claude Code desde aquí

Por qué trabajar desde este directorio: Claude Code lee el .mcp.json, CLAUDE.md y MEMORY.md desde la raíz del proyecto. Al abrir Claude Code aquí, ya tiene todo el contexto configurado.

Paso 2 — Instalar las skills

cp -r skills/n8n-coolify-fullstack ~/.claude/skills/
cp -r skills/make-to-n8n ~/.claude/skills/
cp -r skills/n8n-sdk-rules ~/.claude/skills/

Reinicia Claude Code. Las skills aparecen disponibles automáticamente.

Paso 3 — Configurar tus credenciales

3a. Copiar el template de MCP y rellenar con tus datos:

cp .mcp.json.example .mcp.json

.mcp.json está en .gitignore — tus credenciales nunca se subirán al repo.

Editar .mcp.json y reemplazar los placeholders:

{
  "mcpServers": {
    "n8n-mcp": {
      "env": {
        "N8N_API_URL": "https://TU_N8N_URL/",   ← la / al final es obligatoria
        "N8N_API_KEY": "TU_API_KEY"
      }
    }
  }
}

Para obtener tu API key: n8n → Settings → API → Enable API → Create API Key

3b. Rellenar CLAUDE.md — las secciones 1, 2 y 3 son las más importantes:

• Sección 1: tu URL de n8n, si usas Coolify, microservicios activos
• Sección 2: nombre del proyecto, proceso que automatizas, reglas de negocio
• Sección 3: credenciales disponibles en n8n (nombres exactos), nodos que más usas

3c. Configurar Playwright con tu perfil de Chrome (para validación E2E con sesión activa):

# Encontrar tu perfil de Chrome
ls ~/Library/Application\ Support/Google/Chrome/ | grep -i profile
# Output ejemplo: Profile 2

# En .mcp.json → reemplazar en la sección "playwright":
# --user-data-dir=/Users/TU_USUARIO/Library/Application Support/Google/Chrome/Profile 2

Antes de usar Playwright: crea un perfil Chrome dedicado, inicia sesión en tu n8n y Coolify en ese perfil, y usa esa ruta en el .mcp.json. Así Playwright ya tiene sesión activa cada vez que lo usa Claude.

---

Verificar que todo funciona

Escribe esto en Claude Code después de configurar:

/mcp

→ Debe aparecer n8n-mcp ✅ connected

Luego prueba:

"lista mis workflows activos en n8n"

→ Claude debe devolver tus workflows reales via MCP.

---

Las 6 skills de n8n

Claude las activa automáticamente — no necesitas invocarlas.

Skill	Se activa cuando...
n8n-workflow-patterns	Diseñas un workflow nuevo o eliges arquitectura
n8n-mcp-tools-expert	Usas cualquier herramienta MCP de n8n
n8n-node-configuration	Configuras un nodo específico
n8n-code-javascript	Escribes código JS en un Code node
n8n-expression-syntax	Escribes expresiones {{ }} o hay un undefined
n8n-validation-expert	Hay errores de validación que interpretar

Estas 6 skills se instalan desde el marketplace de Claude Code. La skill n8n-coolify-fullstack (la exclusiva de este kit) la instalaste en el Paso 2.

---

La skill exclusiva: n8n-coolify-fullstack

Combina 5 módulos que trabajan juntos en proyectos de producción:

Módulo	Qué hace
coolify-microservices.md	Gestiona microservicios en Coolify MCP desde Claude: list, get, restart, logs
sticky-notes-patterns.md	4 zonas de documentación obligatorias con posiciones y colores estándar
dual-layer-validation.md	Validación en dos capas: MCP (estructura) + Playwright E2E (visual con sesión)
sub-workflow-patterns.md	Cuándo crear sub-workflows, cómo pasar datos, el gotcha del type: "string"
microservice-integration.md	Integrar microservicios Docker con n8n: patrones síncrono, callback, polling

---

La skill canónica: n8n-sdk-rules

Reglas de generación extraídas directamente del @n8n/workflow-sdk oficial de n8n (v0.12.1). El equipo de n8n escribió este contenido específicamente para guiar a agentes de IA — no es documentación de usuario.

Módulo	Qué contiene
workflow-rules.md	4 reglas estrictas: nunca alwaysOutputData: true, cuándo usar executeOnce: true, elegir el primitivo de control de flujo correcto, credenciales siempre via credentials manager
expression-gotchas.md	Los 3 contextos donde $json es inseguro (AI Agent subnodes, multi-branch fan-in, nodos no inmediatos) + referencia completa de variables y Luxon
node-selection.md	Selección de nodo por caso de uso, triggers, preferencia de nativos sobre Code node, patrones de AI tools y multi-agent
parameter-guides.md	Guías detalladas: IF (operadores completos), Set (tipos), Switch, Webhook (responseMode), HTTP Request (auth), Tool nodes ($fromAI), AI Agent (system vs user message)
best-practices.md	Patrones por categoría: chatbot (memoria compartida, session keys), notificaciones (multi-canal en paralelo), scheduling (condicional > cron complejo), human-in-the-loop (Wait node + resumeUrl)

Se activa automáticamente al crear o editar cualquier workflow n8n. Previene los errores más comunes antes de que ocurran.

---

La skill de migración: make-to-n8n

Convierte escenarios Make (Integromat) a workflows n8n. Se activa automáticamente cuando pegas un JSON exportado de Make o describes un flujo que quieres migrar.

Módulo	Qué contiene
SKILL.md	Tabla de conceptos Make vs n8n, proceso paso a paso, patrones especiales (Iterator, Router, Repeater, Aggregator), ejemplo completo de migración
module-mapping.md	Mapeo de ~80 módulos Make → nodo n8n exacto, con tipo de equivalencia y snippets para módulos sin equivalente directo
expression-conversion.md	Traducción completa de sintaxis: {{N.field}} → {{$node["X"].json.field}}, todas las funciones de texto, fecha, número, array y hashing

Cómo usarla:

"tengo este JSON de Make, conviértelo a n8n"
"migra este escenario de Make a un workflow n8n"
"cómo traduzo este módulo de Make al nodo equivalente en n8n"

---

El subagente workflow-architect

Diseña planes completos de implementación en lenguaje natural:

"actúa como workflow-architect y diseña el plan para:
 recibir un formulario de contacto por webhook, calificar el lead
 con un Code node, guardar en Google Sheets, y enviar email con
 o sin botón de agenda según la calificación"

El subagente produce:

• Diagrama ASCII del flujo
• Tabla de nodos con configuración clave
• Posiciones y contenido de sticky notes por zona
• Secuencia de construcción paso a paso
• Credenciales requeridas y riesgos

---

MCP vs API REST — cuándo usar cada uno

Ver docs/mcp-vs-api.md para la comparativa completa.

Resumen:

• MCP: para construir, editar y validar workflows. Claude entiende n8n semánticamente.
• API REST directa: para operar y monitorear. Scripts, CI/CD, ejecuciones en tiempo real.
• Los dos viven en el mismo .mcp.json — no son excluyentes.

---

Tus workflows

La carpeta workflows/ está vacía intencionalmente. Pon ahí tus propios workflows:

# Exportar desde n8n: ⋮ → Download → guardar el .json aquí
workflows/mi-workflow.json
workflows/sub-mi-proceso.json

Hay un workflow base en workflows/starters/webhook-router-starter.json — un dispatcher con sticky notes en las 4 zonas obligatorias, listo para adaptar.

---

CLAUDE.md y MEMORY.md

CLAUDE.md — Lo rellenas tú una vez. Claude lo lee al inicio de cada sesión y sabe exactamente qué instancia de n8n usas, qué credenciales están disponibles, y qué convenciones seguir. Sin él, Claude empieza sin contexto cada vez.

MEMORY.md — Lo actualiza Claude solo. Cada vez que encuentra y resuelve un error, descubre un gotcha, o valida un patrón que funciona, agrega una entrada. Con el tiempo acumula el conocimiento específico de tu proyecto.

---

Coolify MCP (opcional)

Si usas Coolify para alojar n8n y tus microservicios, agrega el MCP de Coolify en .mcp.json:

"coolify": {
  "command": "npx",
  "args": ["-y", "@masonator/coolify-mcp"],
  "env": {
    "COOLIFY_ACCESS_TOKEN": "TU_TOKEN",
    "COOLIFY_BASE_URL": "https://coolify.tudominio.com/"
  }
}

Token en: Coolify → Profile → API Tokens → Create

Con Coolify MCP puedes pedirle a Claude cosas como:

• "verifica que todos mis microservicios están corriendo"
• "reinicia el servicio X"
• "muéstrame los últimos logs del servicio Y"

---

Requisitos

• n8n self-hosted corriendo y accesible (Coolify, Docker, o local)
• Claude Code instalado: npm install -g @anthropic-ai/claude-code
• Node.js 18+ (para npx)
• Chrome instalado (para Playwright con sesión persistente)

Ver docs/setup-guide.md para instalación paso a paso.

---

Licencia

MIT — Úsalo, modifícalo, compártelo.

---

Creado con Claude Code + La Forja v3.2.0 · Imperio Digital 2026