using-n8n-mcp-skills - Claude MCP Skill

# 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" / "this is getting big" | `n8n-subworkflows` — extract a reusable sub-workflow; search before building |
| "I'll create that credential / open that workflow" (account has >1 instance) | `n8n-multi-instance` — every call hits the currently-targeted instance; reads misroute silently, and an ambiguous credential write fails closed with `INSTANCE_AMBIGUOUS` |

## Skill index

| Skill | Reach for it when |
|---|---|
| `using-n8n-mcp-skills` | This router (auto-loaded). Names the skill that owns your task. |
| `n8n-mcp-tools-expert` | Choosing or calling any n8n-mcp tool; node discovery; credentials; data tables; security audit; templates |
| `n8n-workflow-patterns` | Designing or building a workflow; picking an architecture (webhook / HTTP API / database / AI agent / scheduled / batch) |
| `n8n-node-configuration` | Configuring any node; operation-aware required fields; property dependencies; surgical field edits |
| `n8n-expression-syntax` | Writing `{{ }}`, `$json`/`$node`/`$now`; mapping data between nodes; the transform gatekeeper; Set-node discipline |
| `n8n-validation-expert` | Interpreting validation errors/warnings; false positives; the validation loop; auto-fix; reviewing an existing workflow |
| `n8n-code-javascript` | Any Code node in JavaScript; data access; `this.helpers`; DateTime; SplitInBatches loop patterns |
| `n8n-code-python` | A Code node specifically requested in Python; standard-library limits |
| `n8n-code-tool` | The AI-agent-callable Custom Code Tool (`toolCode`) — returns a string, no `$fromAI`/`$input` |
| `n8n-error-handling` | Webhook/API or unattended workflows; wiring error outputs; retries; 4xx/5xx response shapes; silent failures |
| `n8n-binary-and-data` | Files, images, PDFs, attachments, uploads/downloads, vision; passing a file to/from an agent tool |
| `n8n-subworkflows` | Reusable / multi-step builds; Execute Workflow; extracting shared logic; Define-Below inputs; all-vs-each; exposing a workflow as an agent tool |
| `n8n-agents` | AI Agent / LLM-with-tools / Text Classifier; tool design & `$fromAI`; system prompts; structured output; memory; RAG; human review; chat bots |
| `n8n-multi-instance` | Accounts with multiple instances (the `n8n_instances` tool is present); switching the target instance; verifying before credential writes; recovering from an unexpected `NOT_FOUND`, wrong/empty reads, or an `INSTANCE_AMBIGUOUS` credential-write fail-close |
| `n8n-self-hosting` | *Deployment, not workflow-building* — self-hosting / installing / deploying n8n on a VM (Docker Compose + Caddy, single vs queue mode), or updating / backing up / hardening it. Triggers on its own; not part of the build flow above. |

## n8n-mcp tools — working knowledge from turn one

Qualified names look like `mcp__<server>__<tool>` (`<server>` is usually `n8n-mcp`). This
closes the gap where a tool's full description isn't loaded until first use.

**Two tiers, and how to tell which one you have.** The documentation and validation tools
below work offline and are always present. The `n8n_*` management tools talk to a live n8n
instance and appear **only once one is connected**. If they are absent, nothing is broken
and there is nothing to retry — say so plainly and point the user at the right fix for
their install:

- **Hosted (`https://api.n8n-mcp.com/mcp`)** — sign in through the OAuth prompt the client
  shows on first use, then connect the n8n instance in the dashboard. No environment
  variables, and no API key pasted into a config file.
- **Self-hosted (`npx n8n-mcp`, Docker)** — the server needs `N8N_API_URL` and
  `N8N_API_KEY` in its environment, exported before the client starts.

`n8n_health_check` confirms a working connection and returns the resolved instance.

**Discovery & docs**
- `tools_documentation` — meta-docs for every tool; `{topic:"ai_agents_guide", depth:"full"}` for the agent guide.
- `search_nodes` — find nodes by keyword.
- `get_node` — node info. Takes a single **SHORT-form** `nodeType` (`nodes-base.httpRequest`, `nodes-langchain.agent`), plus `detail` (minimal/standard/full) and `mode` (info/docs/search_properties/versions).
- `validate_node` — validate one node's config in isolation (profiles: minimal/runtime/ai-friendly/strict).
- `search_templates` / `get_template` — the template library (by keyword, nodes, task, metadata).

**Build & edit**
- `n8n_create_workflow` — create from full workflow JSON.
- `n8n_update_partial_workflow` — incremental diff ops (`{id, operations:[…]}`): addNode, updateNode, patchNodeField, addConnection, setNodeGroups, activateWorkflow, etc. Preferred for edits.
- **Canvas groups** (n8n 2.28+) survive your edits without being managed: a grouped node you remove is pruned from its group, and a group n8n can no longer accept is ungrouped so the edit still lands — nodes and connections untouched, every adjustment reported in `details.warnings`. To create or change groups, use the `setNodeGroups` op (full replacement; `[]` ungroups everything). See `n8n-mcp-tools-expert`.
- `n8n_update_full_workflow` — full replacement.
- `n8n_autofix_workflow` — auto-fix common issues.
- `n8n_deploy_template` — deploy a template to the instance.

**Validate** (necessary, not sufficient — always pair with the antipattern scan)
- `validate_workflow` — full JSON in, errors/warnings/fixes out. Node types here are **LONG form** (`n8n-nodes-base.set`).
- `n8n_validate_workflow` — validate a deployed workflow by `{id}` (no node JSON to inspect).

**Inspect & lifecycle**
- `n8n_get_workflow` — fetch a workflow (full / structure / active / filtered / minimal). Use it to verify `connections` after edits; `mode="filtered"` + `nodeNames` reads one heavy node (e.g. long Code source) without pulling the whole workflow, which can truncate client-side.
- `n8n_list_workflows` — list/filter (search before duplicating logic).
- `n8n_delete_workflow`, `n8n_workflow_versions` (history/rollback/diff; `source: "local"` = n8n-mcp's own snapshots, `source: "native"` = n8n's own history including edits people made in the UI — see `n8n-mcp-tools-expert`), `n8n_instances` (multi-instance accounts only: list/switch the target instance — see `n8n-multi-instance`), `n8n_health_check` (returns the resolved `instanceName`, plus an `officialMcp` block saying whether the instance-level MCP server below is configured and reachable).

**Test & run**
- `n8n_test_workflow` — runs real nodes (Code, HTTP, DB writes, sends all fire). Ask the user before running when side effects exist. `method` picks the path: `auto` (default) and `trigger` fire a webhook/form/chat trigger over HTTP on an **active** workflow; `prepare`/`pinned`/`direct` route through n8n's own MCP server and can run a workflow that has no HTTP trigger at all (Manual, Schedule, sub-workflow) — see `n8n-mcp-tools-expert`.
- `n8n_executions` — list/inspect executions. **There is no `execute_workflow` tool.**
- `n8n_evaluations` — evaluation test runs: list runs, aggregated metrics, per-case results (n8n ≥ 2.30), plus `run`/`cancel` to start or stop a run (n8n ≥ 2.32). `run` executes the workflow against its whole dataset — real nodes fire, so ask the user first. A 403 can mean the API key was created before the action's minimum version (re-create it for the testRun scopes), evaluations aren't licensed on the plan, or the key's owner lacks access to the workflow — for `run`/`cancel`, specifically the `workflow:execute` scope.

**Data, folders, credentials, audit**
- `n8n_manage_datatable` — Data Table CRUD, filtering, dry-run. `addColumn`/`deleteColumn`/`renameColumn` change an existing table's columns (the Public API cannot) through n8n's MCP server — `deleteColumn` drops the column's values along with it.
- `n8n_manage_folders` — workflow folder CRUD with contents counts (n8n ≥ 2.19, registered Community tier and up; `projectId` defaults to `personal`). Place workflows via `parentFolderId` on `n8n_create_workflow` or the `moveToFolder` op (n8n ≥ 2.32). Placement is write-only — verify via a folder's `get` counts, never by reading the workflow. `delete` without `transferToFolderId` moves the folder's workflows to the project root and ARCHIVES them — they still exist, but deactivated (`transferToFolderId: "0"` = transfer to project root without archiving).
- `n8n_manage_credentials` — credential CRUD + `getSchema` discovery.
- `n8n_audit_instance` — security audit (hardcoded secrets, unauthenticated webhooks, error-handling gaps).

**Instance-level MCP server** — a second endpoint alongside the Public API, gated on `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+). `n8n_health_check` reports whether it is reachable; without it these calls answer `NOT_CONFIGURED` rather than failing obscurely.
- `n8n_manage_agents` — persisted n8n **Agents**: a standalone assistant artifact with its own lifecycle (model, instructions, skills, tasks, memory, channels), **not** the AI Agent workflow node. `call` runs it live with real credentials and may return `approvals[]`; `publish` only when the user asks. See `n8n-agents`.
- `n8n_explore_node_resources` — resolve a node's live dropdown / resource-locator values through a real credential instead of guessing an ID. See `n8n-node-configuration`.
- `n8n_list_catalog` — list `projects` (to get a `projectId`) or `tags`. The one tool here that also works without the token.
- The same server backs `n8n_test_workflow` `prepare`/`pinned`/`direct`, `n8n_workflow_versions` `source: "native"`, and the `n8n_manage_datatable` column actions. Those are additionally gated per workflow on its "Available in MCP" setting; a refusal reads `WORKFLOW_NOT_EXPOSED`, and turning the setting on (`exposeToMcp: true`) is a visible, persistent change — ask the user first.

> **Node-type form trap:** `get_node` / `validate_node` take SHORT form (`nodes-base.set`);
> workflow JSON inside `validate_workflow` / `n8n_create_workflow` uses LONG form
> (`n8n-nodes-base.set`). Mixing them is a common, silent mistake — see `n8n-mcp-tools-expert`.

## The protocol, in order

1. Recognize the matching skill from the index and **invoke it before the first MCP call**.
2. Skim `tools_documentation` once per session to refresh the tool surface if you're unsure.
3. `get_node` before configuring any node — read the live schema, don't assume.
4. Build / edit, then **`validate_workflow` before activating** and **`n8n_get_workflow` after** to check `connections`.
5. Surface any drift you notice (missing tool, changed parameter, diverging behavior).

## When in doubt

- **Can't find a workflow the user built in the UI?** The most common cause is per-workflow
  MCP access being off. Ask them to open it in n8n, go to Settings, and enable MCP access.
- **User says it's broken?** Believe them. Re-check parameters against `get_node`, trace
  data references, inspect the execution. See `n8n-validation-expert`.
- **No skill fits and the task is non-trivial?** Ask before guessing.

These are opinionated best practices, not laws. Disagree with a call? It's all markdown —
edit the skill.