本文へ移動
cccskills
無料GitHub で公開

using-n8n-mcp-skills

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.

インストール方法を見る

含まれるファイル(2)

  • SKILL.md17.1 KB
  • README.md2.9 KB

SKILL.md(原文)

インストールする前に、エージェントに与えられる指示の中身を確認できます。

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 typeVersions, 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. A green test run isn't proof either: JS errors inside {{ }} resolve silently to null (a Filter with a broken condition drops every item and still shows success), so inspect the output values. See n8n-expression-syntax.
  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.

ThoughtInvoke
"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

SkillReach for it when
using-n8n-mcp-skillsThis router (auto-loaded). Names the skill that owns your task.
n8n-mcp-tools-expertChoosing or calling any n8n-mcp tool; node discovery; credentials; data tables; security audit; templates
n8n-workflow-patternsDesigning or building a workflow; picking an architecture (webhook / HTTP API / database / AI agent / scheduled / batch)
n8n-node-configurationConfiguring any node; operation-aware required fields; property dependencies; surgical field edits
n8n-expression-syntaxWriting {{ }}, $json/$node/$now; mapping data between nodes; the transform gatekeeper; Set-node discipline
n8n-validation-expertInterpreting validation errors/warnings; false positives; the validation loop; auto-fix; reviewing an existing workflow
n8n-code-javascriptAny Code node in JavaScript; data access; this.helpers; DateTime; SplitInBatches loop patterns
n8n-code-pythonA Code node specifically requested in Python; native runtime (_items/_item only, imports blocked by default, legacy _input code fails)
n8n-code-toolThe AI-agent-callable Custom Code Tool (toolCode) — returns a string, no $fromAI/$input
n8n-error-handlingWebhook/API or unattended workflows; wiring error outputs; retries; 4xx/5xx response shapes; silent failures
n8n-binary-and-dataFiles, images, PDFs, attachments, uploads/downloads, vision; passing a file to/from an agent tool
n8n-subworkflowsReusable / multi-step builds; Execute Workflow; extracting shared logic; Define-Below inputs; all-vs-each; exposing a workflow as an agent tool
n8n-agentsAI Agent / LLM-with-tools / Text Classifier; tool design & $fromAI; system prompts; structured output; memory; RAG; human review; chat bots
n8n-multi-instanceAccounts 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-hostingDeployment, 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.

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

同じリポジトリのスキル

概要と使いどころ

Design n8n AI agents the right way. Use when building or editing any @n8n/n8n-nodes-langchain.* AI node — an AI Agent, LLM chain, Text Classifier, or Information Extractor — and whenever the user mentions AI agents, LLM with tools, tool calling, $fromAI, system prompts, agent memory, sessionId, structured/JSON output, output parser, RAG, vector store, a chat assistant/bot, or human-in-the-loop review. Covers Agent-vs-chain-vs-classifier choice, the model/memory/tools/outputParser slots, tool names/descriptions as prompt, structured output with autoFix, memory, RAG, human review, and chat topologies.

日本語の概要は準備中です。原文の説明を表示しています。

czlonkowski/n8n-skills6,4112026年10月9日 更新

Handle files and binary data in n8n correctly. Use when working with files, images, PDFs, attachments, uploads or downloads, base64, vision/multimodal input, or when an AI agent needs a file as tool input or output — and whenever the user mentions $binary, binaryPropertyName, "read the PDF", "attach the file", "send the image", Merge losing binary, or a CDN for chat images. Covers the $binary vs $json split, reading/writing binary, keeping binary alive across transforms with Merge, the agent-tool binary boundary, and the CDN/URL requirement for chat surfaces.

日本語の概要は準備中です。原文の説明を表示しています。

czlonkowski/n8n-skills6,4112026年10月9日 更新

Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with this.helpers / the $helpers global, working with dates using DateTime, troubleshooting Code node errors, choosing between Code node modes, or doing any custom data transformation in n8n. Always use this skill when a workflow needs a Code node — whether for data aggregation, filtering, API calls, format conversion, batch processing logic, or any custom JavaScript. Covers SplitInBatches loop patterns, cross-iteration data, pairedItem, and real-world production patterns. Also use when asked why a Code node or workflow is slow, which execution mode is faster, or how to cut per-item overhead on large datasets. EXCEPTION — for the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode, a tool attached to an AI Agent), use the n8n-code-tool skill instead; it has a different runtime contract.

日本語の概要は準備中です。原文の説明を表示しています。

czlonkowski/n8n-skills6,4112026年10月9日 更新

Write Python in n8n Code nodes (native Python, `language` pythonNative, n8n 2.x). Use when the user explicitly wants Python in a Code node, when migrating old Pyodide/"Python (Beta)" code that used _input/_json/_node/_now, or when a Python Code node fails with NameError, "Security violations detected", "Import of standard library module … is disallowed", "__build_class__ not found", "A 'json' property isn't a dictionary", or "Python runner unavailable". Covers the only two variables (_items/_item), dict-only access, imports blocked by default, the sandbox's denied builtins, accepted return shapes, and how errors interact with onError. JavaScript is the default for Code nodes — native Python has no n8n helpers and, by default, no imports. EXCEPTION — for Python in the AI-agent-callable Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode), use the n8n-code-tool skill instead (input is _query, return must be a string).

日本語の概要は準備中です。原文の説明を表示しています。

czlonkowski/n8n-skills6,4112026年10月9日 更新

Write JavaScript or Python for the n8n Custom Code Tool (@n8n/n8n-nodes-langchain.toolCode) — the AI-agent-callable tool, NOT the workflow Code node. Use when building a Code Tool attached to an AI Agent, writing code that an LLM will invoke, parsing the `query` input, returning a string result, defining an input schema for structured arguments (specifyInputSchema, jsonSchemaExample, DynamicStructuredTool), or troubleshooting errors like "Wrong output type returned", "No execution data available", "The response property should be a string, but it is an object", "Cannot assign to read only property 'name'", or an AI agent that refuses to call the tool. Covers the critical differences between Code node and Code Tool: return format (string vs `[{json:{...}}]`), unavailability of `$fromAI`/`$input`/`$helpers` in the Code Tool sandbox, naming rules for AI invocation, and when to use `toolWorkflow`/HTTP Request Tool instead.

日本語の概要は準備中です。原文の説明を表示しています。

czlonkowski/n8n-skills6,4112026年10月9日 更新

Wire n8n error handling so failures are loud, structured, and recoverable. Use when building any webhook/API workflow, a scheduled or unattended workflow, or any path where a silent failure would drop user-visible work — and whenever the user mentions error handling, onError, continueErrorOutput, error branches/outputs, retries, retryOnFail, Respond to Webhook status codes, 4xx/5xx, Error Trigger, or "my workflow fails silently". Covers per-node error outputs and wiring, retry/self-healing, error-trigger workflows, and 4xx/5xx response shapes.

日本語の概要は準備中です。原文の説明を表示しています。

czlonkowski/n8n-skills6,4112026年10月9日 更新

czlonkowski のスキルをすべて見る

このスキルの問題を報告する