/using-n8n-mcp-skills

name: using-n8n-mcp-skills
description: "Use when building, editing, validating, testing, or debugging an n8n workflow through the n8n-mcp MCP server — designing a flow, configuring a node, writing an expression or Code node, wiring credentials, or fixing one that misbehaves. The entry-point skill for the n8n-mcp-skills pack: it routes you to the right specialist skill, gives working knowledge of every n8n-mcp tool from turn one, and states the rules that keep workflows from breaking in production. Always consult it first on any n8n, workflow, node, or automation task — even a quick one-off, and even when the user names no skill — because n8n's surface drifts between versions and the specialist skills prevent silent failures."

Using the n8n-mcp Skills

This is a **router**, not a reference. It tells you which skill owns the rules for what you're about to do. The skill bodies hold the actual guidance — invoke them with the Skill tool. When in doubt, load more skills rather than fewer.

The community **n8n-mcp** server and n8n itself move faster than any model's training cutoff. Tool names, parameters, node `typeVersion`s, and default behaviors drift between releases. When you spot drift — a tool a skill names doesn't exist, a parameter shape doesn't match what `get_node` returns, behavior differs from what a skill describes — trust the **live tool**, tell the user, and suggest updating the pack and the instance.

Non-negotiables

Three rules with no exceptions. Each one prevents a class of workflow that looks correct but breaks in production.

1. **Invoke the relevant skill before any n8n action** — not just before MCP calls. Before writing an expression, configuring a node, designing a workflow, wiring a connection, or writing Code, invoke the matching skill. PreToolUse hooks remind you on the highest-impact tool calls, but they exist **only in the Claude Code plugin install**. Everywhere else — Claude.ai skill uploads, and any client that loads this pack as an Agent Plugin (Codex, Cursor, Copilot and the rest) — nothing nudges you and the responsibility is entirely yours. Assume you are un-hooked unless you have seen a hook fire this session. 2. **Validate AND verify before activating.** Run `validate_workflow` (or `n8n_validate_workflow` by id) before you activate, and call `n8n_get_workflow` after every create or update to inspect the `connections` object. Validation alone misses silently dropped wires, Merge index off-by-one, and error outputs that were never wired. Validation passing means the JSON is well-formed — not that the workflow is correct. 3. **Secrets never go in text fields.** Tokens, API keys, and passwords always go through the n8n credential system. If no native node exists, use the HTTP Request node with the official credential type. A Set node holding a token referenced via `{{ $json.token }}` is a leak with extra steps. See `n8n-mcp-tools-expert`.

Lean on skills, not training data

n8n changes constantly. "Remembered" parameter names are often silently wrong — they validate as plain strings and then do nothing at runtime. Trust the skills and the live tools (`get_node`, `search_nodes`, `tools_documentation`) over recollection. If a skill contradicts your memory, trust the skill. If `get_node` contradicts a skill, trust the tool and flag the drift.

Strong defaults

Each skill owns its own exceptions; these are the defaults.

• **The Code node is a last resort.** Expression first, then an arrow function inside Edit

Fields, then a Code node only when neither can do the job. See `n8n-code-javascript`.

• **A Set node feeding 0–1 consumers is almost always wrong.** Inline the expression at

the consumer instead. See `n8n-expression-syntax`.

• **Per-item iteration is automatic.** Don't add a Loop Over Items node to "make it loop"

when default per-item execution already handles the case.

• **Configure from the live schema, never from memory.** `get_node` before you set

parameters. See `n8n-node-configuration`.

Red flags: "about to ___" → invoke ___

If you catch yourself thinking any of these, stop and invoke the named skill first.

| Thought | Invoke | |---|---| | "This workflow is simple, I'll just build it" | `n8n-workflow-patterns` — most "simple" flows ship at 10+ nodes | | "I'll add a Set node to map these fields" | `n8n-expression-syntax` — Set feeding ≤1 consumer is the #1 antipattern | | "I'll just use a Code node, it's easier" | `n8n-code-javascript` — the bar is high; most reaches are expressions or Edit Fields | | "The user mentioned data, I'll write Python" | `n8n-code-javascript` — default JS; Python (`n8n-code-python`) only on explicit ask | | "I'm writing code an AI agent will call" | `n8n-code-tool` — a different runtime contract from the Code node | | "Date math — I'll drop in a DateTime node" | `n8n-expression-syntax` — Luxon inline is almost always right | | "I'll wire a Merge with 3 sources" | `n8n-node-configuration` — Merge defaults to 2 inputs; the 3rd silently drops | | "Validation passed, I'm ready to activate" | `n8n-validation-expert` + `n8n-workflow-patterns` — run the antipattern scan | | "Validation threw an error I don't understand" | `n8n-validation-expert` — what each error and warning means, and which are must-fix vs. best-practice advice | | "I'll reference `$json.x` here" | `n8n-expression-syntax` — prefer `$('Node').item.json.x` in branchy workflows | | "This webhook/scheduled flow is happy-path only" | `n8n-error-handling` — wire an error branch on every fallible node; 4xx caller faults, 5xx yours | | "I'll pass this file/image through as JSON" | `n8n-binary-and-data` — file contents live in `$binary`, and can't cross the agent-tool boundary | | "I'll wire up an AI agent and give the model some tools" | `n8n-agents` — tool names & descriptions ARE the prompt; memory, structured output, and topology have traps | | "I'll copy this logic into another workflow" /