n8n MCP + Claude Code: depura workflows con IA conversacional

Automation

•1 de abril de 2026•5 min read•Por Daily Miranda Pardo

Si ya usas n8n para automatizar procesos y Claude Code como asistente de desarrollo, hay una capa que pocos conocen y que multiplica la productividad: el MCP server de n8n. Con él puedes crear, modificar, depurar y lanzar workflows directamente desde una conversación con Claude Code, sin tocar la interfaz gráfica de n8n. En este artículo verás cómo configurarlo y cómo resolver los errores más frecuentes en tiempo real. Si aún no tienes claro cómo se integra Claude Code con n8n a nivel general, empieza por nuestra guía de automatizaciones n8n con Claude Code.

Qué es el MCP de n8n y por qué cambia cómo trabajas

El Model Context Protocol (MCP) es el estándar que permite a Claude Code hablar directamente con herramientas externas. El MCP de n8n expone las operaciones más importantes de la API de n8n como herramientas que Claude puede invocar en tiempo real:

search_workflows — busca workflows por nombre o descripción
get_workflow_details — lee la estructura completa de un workflow
create_workflow_from_code — crea un workflow nuevo desde código TypeScript
update_workflow — modifica un workflow existente
execute_workflow — lanza una ejecución manualmente
get_execution — consulta el resultado de una ejecución
validate_workflow — detecta errores estructurales antes de guardar

Lo que esto significa en la práctica: en lugar de abrir el editor, buscar el nodo con el error, editar la expresión y guardar, le dices a Claude "el Output Parser está fallando porque devuelve JSON envuelto en markdown" y él lo lee, lo corrige y lo actualiza en segundos.

Configurar el MCP de n8n en Claude Code

Para conectar el MCP de n8n a tu instancia de Claude Code necesitas añadirlo al fichero de configuración MCP. Si usas la versión de escritorio o CLI, el fichero está en ~/.mcp.json:

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_API_URL": "https://tu-instancia.n8n.cloud/api/v1",
        "N8N_API_KEY": "tu-api-key"
      }
    }
  }
}

Obtén la API key en n8n → Settings → API → Create API key. Con esto activo, Claude Code verá todos los workflows de tu instancia como contexto directo.

Depurar el error "Model output doesn't fit required format"

Uno de los errores más frecuentes al usar nodos de Output Parser en n8n ocurre cuando el modelo devuelve JSON envuelto en un bloque de código markdown:

Error: Model output doesn't fit required format
Received: ```json\n{ "title": "...", ... }\n```
Expected: { "title": "...", ... }

Causa: el LLM añade ```json alrededor de la respuesta aunque el prompt no lo pida.

Solución con Claude Code + MCP:

Claude lee el nodo AI Agent vinculado al Output Parser con get_workflow_details
Detecta que el system message no incluye instrucción explícita sobre formato
Añade al system message: "IMPORTANT: Return ONLY raw JSON without markdown code blocks or any surrounding text."
Actualiza el workflow con update_workflow

// Instrucción que resuelve el error en el system message del AI Agent
const systemMessage = `
Eres un asistente de contenido SEO.
IMPORTANTE: Devuelve ÚNICAMENTE JSON puro, sin bloques de código markdown (sin \`\`\`json ni \`\`\`).
Tu respuesta debe empezar directamente con { y terminar con }.
`;

Corregir errores de expresión y operadores en nodos Switch/If

Otro error habitual es el nodo Switch o IF que falla con:

Cannot read properties of undefined (reading 'caseSensitive')

Esto ocurre cuando el operador de una condición pierde sus propiedades internas al copiar o exportar el workflow. El nodo guarda un objeto incompleto.

Cómo diagnosticarlo y resolverlo con Claude Code:

# Claude ejecuta esto via MCP
get_workflow_details({ workflowId: "1qbFRYi7cx08rSY4" })
# Busca nodos de tipo "n8n-nodes-base.switch" o "n8n-nodes-base.if"
# Detecta condiciones con operator: {} vacío

La corrección: eliminar la condición afectada y volver a definirla con operator: { type: "string", operation: "equals" } explícito. Claude lo hace directamente con update_workflow sin que tengas que abrir el editor.

Controlar el ciclo de vida del workflow desde la terminal

Con el MCP activo puedes gestionar todo el ciclo desde Claude Code:

# Activar un workflow
publish_workflow({ workflowId: "abc123" })

# Ejecutarlo manualmente con datos de prueba
execute_workflow({
  workflowId: "abc123",
  payload: { topic: "Integración IA en e-commerce" }
})

# Consultar el resultado de la última ejecución
get_execution({ executionId: "xyz789" })

# Archivar un workflow obsoleto
archive_workflow({ workflowId: "old456" })

Esto es especialmente útil en pipelines de contenido: puedes lanzar la generación de un artículo, monitorizar la ejecución y comprobar el resultado sin salir del terminal donde tienes abierto Claude Code.

Validar antes de guardar: evita errores en producción

El paso más infravalorado es validate_workflow. Antes de hacer update_workflow o create_workflow_from_code, siempre valida:

const result = await validate_workflow({ code: workflowCode });
// Si hay errores, Claude los lee y corrige en el mismo turno
// Solo llama a create/update cuando result.valid === true

Errores típicos que detecta la validación antes de que fallen en producción:

Nodos sin conectar a la cadena principal
Credenciales referenciadas que no existen
Expresiones con sintaxis incorrecta ({{ $json.field }} vs {{ $json["field"] }})
Tipos de datos incompatibles entre nodos conectados

Del error al fix en menos de 2 minutos

La combinación n8n MCP + Claude Code convierte el debugging de workflows en un proceso conversacional. En lugar de navegar entre pestañas, leer logs, editar JSON a mano y guardar, describes el problema en lenguaje natural y Claude:

Lee el workflow completo con get_workflow_details
Identifica el nodo y la línea exacta del error
Propone y aplica la corrección con update_workflow
Valida el resultado con validate_workflow

Para integraciones más complejas o si quieres montar este stack para tu negocio, revisa nuestro servicio de integración de IA y el programa de desarrollo con IA.

¿Tienes un workflow n8n atascado o quieres montar un pipeline de contenido como este desde cero? Hablemos de tu proyecto y lo arrancamos esta semana.