N8n Skill

---
name: automatelab-n8n
description: build, debug, or extend n8n workflows with generated JSON, custom nodes, AI agents, code execution, linting, diagnostics, and live instance control via REST
version: 0.4.0
license: MIT
homepage: https://github.com/ratamaha-git/n8n-mcp
compatibility:
  hosts:
    - claude-code
    - cursor
    - claude-desktop
    - windsurf
    - vscode
    - zed
    - continue
    - cline
    - jetbrains
    - warp
metadata:
  npm: "@automatelab/n8n-mcp"
  mcpName: io.github.ratamaha-git/n8n-mcp
---

# n8n

use this skill when building, debugging, extending, or deploying n8n workflows. pair it with the `@automatelab/n8n-mcp` MCP server to access 9 tools covering stateless workflow generation and linting, plus live instance management via REST API. the skill routes you to the right tool and shows you the standard chains for common tasks.

## intent

the n8n skill maps user requests onto stateless and live-instance tools. generate workflows from plain english descriptions, scaffold custom TypeScript nodes, diagnose failed executions, lint JSON for deprecated schemas, and push workflows to a live n8n instance. use when the user wants to author or troubleshoot any part of an n8n automation, from design to deployment to post-mortem.

## inputs

**MCP server connection:**
- `@automatelab/n8n-mcp` npm package loaded into your MCP host (Cursor, Claude Desktop, VSCode, etc.)
- MCP config file with server entrypoint (see setup section)

**for stateless tools (no env vars needed):**
- workflow description (plain english)
- workflow JSON (for linting or auditing)
- execution JSON (for diagnostics)

**for live-instance tools (requires env vars):**
- `N8N_API_URL`: full URL to n8n instance (e.g. `https://n8n.example.com`)
- `N8N_API_KEY`: API key from n8n Settings > API > Create API key (format: `n8n_...`)
- optional: workflow ID, execution ID, filter tags, pagination cursor

**external services (optional, only if workflow uses them):**
- LangChain API key (if generating AI agents)
- third-party API keys for webhook, HTTP, database, CRM nodes (not managed by this skill)

## procedure

### chain 1: generate, lint, and deploy a workflow

1. user describes a flow in plain english (e.g. "fetch leads from Salesforce, enrich with email, send to Slack").
2. call `workflow.generate` with the description verbatim as input. output: workflow JSON.
3. call `workflow.lint` on the JSON. output: list of issues (if any).
4. **decision point**: if lint returns errors, edit the JSON inline or re-prompt the user to clarify intent. repeat steps 2-3 until clean.
5. **decision point**: if `N8N_API_URL` and `N8N_API_KEY` env vars are present, call `workflow.create` with the JSON. output: workflow object with ID.
6. call `workflow.activate` with the workflow ID to flip active status to `true`. output: updated workflow object.
7. return workflow ID and summary of deployed workflow.

### chain 2: audit a deployed workflow

1. call `workflow.list` with optional filters (name, tags, active status). output: paginated list of workflows.
2. user picks a workflow or you pick by ID.
3. call `workflow.get` with workflow ID. output: full workflow JSON.
4. call `workflow.lint` on the JSON. output: list of issues.
5. **decision point**: if lint flags deprecations or schema errors, summarize the findings and suggest fixes.
6. return audit report and remediation steps.

### chain 3: diagnose a failed execution

1. call `execution.list` with filter `status: "error"` and pagination. output: list of failed executions.
2. user picks an execution or you pick the most recent.
3. call `execution.list` again with `includeData: true` and the execution ID to fetch full body. output: execution JSON with node-by-node data.
4. call `execution.explain` with the execution JSON. output: diagnosis report (missing items, unresolved expressions, token usage, routing logic).
5. **decision point**: if the report explains the issue (e.g. "IF node routed to other branch"), summarize. if not, inspect the workflow node's `parameters` block and `references/expressions.md` for expression logic.
6. return diagnosis and next steps.

### chain 4: write or debug a code node

1. user describes what the Code node should do or pastes a failing Code node snippet.
2. **decision point**: if writing from scratch, generate inline JS. if debugging, run `execution.explain` on the execution that hit the Code node.
3. **decision point**: if the diagnosis points to a Code node issue, load `references/code-node.md` for sandbox limits, return-shape contract, and common failures.
4. write or patch the Code node with the correct shape (return array of objects, handle `$input.all()`, etc.).
5. return the Code node parameters block.

### chain 5: scaffold a custom n8n node

1. user describes the node's purpose (e.g. "custom Shopify order importer").
2. call `node.scaffold` with the description. output: INodeType TypeScript file with boilerplate.
3. user fills in authentication, resource/operation logic, and return schema.
4. user publishes to npm and configures n8n to load the package.
5. return scaffolded file and packaging instructions.

### chain 6: build an AI agent workflow

1. user says "build an AI agent that does X" or you detect multi-step reasoning in their description.
2. call `workflow.generate` with the description. the tool detects AI-agent intent and emits a LangChain cluster (nodes: `ai_languageModel`, `ai_memory`, `ai_tool`, plus decision/loop nodes).
3. call `workflow.lint` on the result.
4. **decision point**: if lint flags "AI Agent without ai_languageModel", load `references/ai-agents.md` for topology, connection types, and sub-node catalog. add the missing language model node.
5. **decision point**: if the agent needs tools (e.g. call an API, query a database), scaffold tool nodes using the reference.
6. return the complete agent workflow JSON.

## decision points

- **if user has env vars (`N8N_API_URL`, `N8N_API_KEY`)**: use live-instance tools (`workflow.list`, `workflow.get`, `workflow.create`, `workflow.activate`, `execution.list` with `includeData: true`). else: use only stateless tools.
- **if lint returns errors**: do not return the workflow. either fix inline or ask the user to clarify intent. re-run lint.
- **if lint returns warnings only**: return the JSON and a one-line summary of warnings. user decides whether to fix.
- **if execution.explain output doesn't explain the issue**: manually inspect the workflow node's `parameters` block for expression logic. load `references/expressions.md` if the user is unfamiliar with `$json`, `$input.all()`, or `$("Node Name")` syntax.
- **if the user mentions "loop over an array" or "process N items at a time"**: load `references/iteration.md` to distinguish Split Out vs Loop Over Items vs Aggregate.
- **if lint flags a deprecated node type**: load `references/deprecations.md` for the replacement node and migration path.
- **if the user describes multi-step reasoning, goal-setting, or tool use**: detect AI-agent intent in the description and load `references/ai-agents.md` before generating.
- **if a Code node fails silently or returns unexpected shape**: load `references/code-node.md` for sandbox limits, return contract, and common pitfalls.
- **if rate limiting occurs** (429 from n8n API): retry with exponential backoff (1s, 2s, 4s). if the user hits the limit repeatedly, suggest pagination or workflow batching.
- **if API key expires** (401 auth error): ask the user to re-generate the key from n8n Settings > API and update env vars.
- **if execution.list returns 0 executions**: the workflow has not run yet or all executions are outside the time filter. ask the user to check the workflow is active and has been triggered.
- **if workflow.generate produces a workflow with unresolved expressions** (e.g. `{{ $json.missing_field }}`): run execution.explain on a test execution to surface the field name mismatch.

## output contract

**workflow.generate output:** workflow JSON conforming to n8n IWorkflow schema (keys: `name`, `nodes`, `connections`, `active`, `nodeTypes`, optional `settings`).

**workflow.lint output:** array of issue objects, each with `level` (error|warning), `node` (string or null), `message` (string).

**execution.explain output:** object with keys: `diagnosis` (string summary), `itemDrops` (array of node names where items disappeared), `unresolvedExpressions` (array of expression strings), `llmTokenUsage` (object with `prompt_tokens`, `completion_tokens`, optional), `flowPath` (array of nodes executed in order).

**workflow.create output:** workflow object with `id` (string), `name`, `nodes`, `connections`, `active` (false on creation), `createdAt`, `updatedAt`.

**workflow.activate output:** updated workflow object with `active` (true or false).

**workflow.list output:** object with keys: `data` (array of workflow summaries), `nextCursor` (string or null), `count` (number of results).

**workflow.get output:** full workflow JSON with `id`, `name`, `nodes`, `connections`, `active`, `settings`, `tags`, `createdAt`, `updatedAt`.

**execution.list output:** object with keys: `data` (array of execution summaries, or full execution JSON if `includeData: true`), `nextCursor` (string or null), `count` (number of results).

**node.scaffold output:** single TypeScript file (string) with INodeType class, properties block, execute method stub, and JSDoc comments.

all outputs are JSON (except node.scaffold, which is TypeScript source).

## outcome signal

**workflow generation and deployment:**
- `workflow.generate` produces valid JSON (no parse errors).
- `workflow.lint` returns 0 errors after generation or editing.
- `workflow.create` returns a workflow object with an `id`.
- `workflow.activate` returns `active: true`.
- user can open the workflow in n8n UI and see all nodes connected with no red error badges.

**execution diagnosis:**
- `execution.explain` output is readable and addresses the user's question (e.g. "Node X returned 0 items because IF condition was false").
- user can trace the flow path and understand where items were lost or expressions failed.
- user can copy the diagnosis to their team slack or ticket.

**code node writing:**
- Code node is pasted or written into the n8n UI and executes without errors on test data.
- output matches the expected shape (array of objects with expected keys).

**node scaffolding:**
- `node.scaffold` returns a TypeScript file that compiles (no syntax errors).
- user can fill in the blanks and publish to npm.

**workflow audit:**
- `workflow.lint` flags any deprecated nodes, missing credentials, broken connections, or schema violations.
- user can fix issues before deploying to production.

---

## server setup

add the n8n MCP server to your MCP config file. location depends on your editor:
- **Cursor**: `~/.cursor/mcp.json`
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **VSCode (with Continue)**: `.vscode/settings.json` under `continue.mcp.servers`
- **other hosts**: consult your editor's MCP docs.

**minimal config (stateless tools only):**

```json
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"]
    }
  }
}

full config (live-instance tools):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "n8n_abcdef123456"
      }
    }
  }
}

to get an API key:

1. log into your n8n instance.
2. click Settings (bottom left).
3. click API.
4. click Create API key.
5. copy the key (format: n8n_...) and paste into your MCP config.

edge cases:

• if you have multiple n8n instances, create separate server entries in your config (e.g. n8n-prod, n8n-dev).
• if you're using n8n Cloud, your API URL is https://api.n8n.cloud.
• if the npx command hangs, check your internet connection and npm cache (npm cache clean --force).

reference docs

the skill keeps itself small to preserve your context window. load reference docs only when the task needs deeper detail:

• references/expressions.md: $json, $input.all(), $("Node Name"), auto-iteration, advanced syntax. load when: writing or debugging expressions, user mentions $json[0] or "why is my expression empty".
• references/ai-agents.md: LangChain cluster topology, ai_languageModel / ai_memory / ai_tool connection types, sub-node catalog, routing. load when: building an AI agent or lint flags "AI Agent without ai_languageModel".
• references/code-node.md: Code node return-shape contract, sandbox limits, common failures, debugging tips. load when: writing a Code node or user reports "Code node fails silently".
• references/workflow-json.md: nodes / connections structure, required fields, credential block, examples. load when: hand-editing workflow JSON or merging workflows.
• references/iteration.md: Split Out vs Loop Over Items vs Aggregate, when to use each, performance trade-offs. load when: user says "loop over an array" or "process N items at a time".
• references/deprecations.md: retired node types and replacement recommendations. load when: lint flags a deprecation or user is migrating an old workflow.

developed by AutomateLab. source: github.com/ratamaha-git/n8n-mcp. ```