# n8n-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/ratamaha-git/n8n-mcp  
**GitHub Stars:** 14  
**npm Downloads (last month):** 346  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/n8n-mcp

## Description
MCP server for n8n: scaffold nodes, generate workflows (incl. AI agents), lint workflow JSON.

## Tools
Capabilities this server exposes over MCP:

- **node_scaffold** — Scaffold a TypeScript skeleton for an n8n custom node from a plain-English description. Returns a single TypeScript file implementing INodeType with description, credentials reference, and an execute method stub. Pure code generation — no network, no filesystem writes.
- **workflow_generate** — Generate a valid n8n workflow JSON from a plain-English description. Handles webhook/schedule/RSS triggers, common action nodes (Slack, Google Sheets, Discord, Gmail, Notion, HTTP), and AI Agent setups (LangChain root agent + chat model + memory + optional HTTP tool, wired with ai_languageModel / ai_memory / ai_tool connections). Returns workflow JSON with unique node IDs, connections, positions, and typeVersion on every node. Output is non-deterministic (random node IDs and webhook paths).
- **workflow_lint** — Lint an n8n workflow JSON. Returns concrete errors and warnings: missing credentials, deprecated node types (Function -> Code, spreadsheetFile -> convertToFile/extractFromFile), broken connections, missing or non-numeric typeVersion, duplicate node names or IDs, AI Agent missing ai_languageModel sub-node, Webhook missing webhookId, IF node still on v1 condition schema, rate-sensitive nodes without retries, Code-node sandbox violations, expression staleness (`$('NodeName')` referencing missing nodes), manualTrigger in active workflows, disabled-but-wired nodes, empty Set nodes, HTTP method/body mismatches, Schedule trigger DST risk, credential drift, webhook test paths in active workflows. Deterministic, rule-based.
- **workflow_diff** — Semantic diff between two workflows. Reports nodes added / removed / modified (with field-level deltas: type, typeVersion, parameters, credentials, disabled, position), connection topology changes, and settings drift. Ignores noise (small position deltas, createdAt/updatedAt). Pair with workflow_get to compare deployed vs local. Deterministic.
- **execution_explain** — Diagnose a failed or surprising n8n execution. Paste the execution JSON (from the n8n UI 'Show details' or `GET /executions/:id?includeData=true`); returns a per-node summary highlighting nodes that returned 0 items, unresolved `={{ ... }}` expressions, errors with hints, and LLM token usage. Hits the most common debugging pain point: items 'silently disappearing' between nodes. Deterministic, rule-based.
- **execution_replay** — Build a self-contained replay workflow that exercises a single node from a larger workflow. The replay workflow is Manual Trigger -> Replay Seed (Code node with pinned items) -> target node. Optional `inputItems` or an `execution` payload pins what the target sees. Useful for iterating on one stubborn node without re-running the whole pipeline. Returns workflow JSON ready to import or push via workflow_create.
- **execution_timeline** — Render an n8n execution as a per-node timeline: start offset, duration, items in/out, error flag. Complements execution_explain — that one surfaces *why*, this surfaces *when*. Output is a markdown table sorted by start time. Deterministic.
- **workflow_list** — List workflows from a live n8n instance (requires N8N_API_URL + N8N_API_KEY env vars). Returns id, name, active, nodeCount, updatedAt, tags. Filter by active, tags, name. Use this when the user asks 'what workflows do I have?' or before workflow_get.
- **workflow_get** — Fetch a single workflow JSON by id from a live n8n instance (requires N8N_API_URL + N8N_API_KEY). Returns the full nodes/connections payload — pair with workflow_lint to audit a deployed workflow.
- **workflow_create** — Create a workflow on a live n8n instance (requires N8N_API_URL + N8N_API_KEY). Strips read-only fields (id, active, createdAt, ...) before posting. Workflows are created inactive — call workflow_activate afterward. Pairs with workflow_generate for end-to-end 'describe -> deploy'.
- **workflow_activate** — Activate or deactivate a workflow on a live n8n instance (requires N8N_API_URL + N8N_API_KEY). Pass `active: false` to deactivate. Idempotent — re-activating an already-active workflow is a no-op on n8n's side.
- **execution_list** — List recent executions from a live n8n instance (requires N8N_API_URL + N8N_API_KEY). Filter by workflowId, status (success|error|waiting), limit. Pass `includeData: true` to get the full execution body (large) — pair with execution_explain to diagnose a specific failure.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "n8n-mcp": {
    "command": "npx",
    "args": ["-y","@automatelab/n8n-mcp"],
    "env": {
      "N8N_API_URL": "",
      "N8N_API_KEY": "",
      "N8N_MCP_READ_ONLY": "",
      "N8N_MCP_DISABLED_TOOLS": "",
      "N8N_MCP_ALLOWED_WORKFLOW_IDS": "",
      "N8N_MCP_ALLOWED_TAGS": ""
    }
  }
}
```

**Requires environment variables:** `N8N_API_URL`, `N8N_API_KEY`, `N8N_MCP_READ_ONLY`, `N8N_MCP_DISABLED_TOOLS`, `N8N_MCP_ALLOWED_WORKFLOW_IDS`, `N8N_MCP_ALLOWED_TAGS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What n8n-mcp MCP server does

The n8n-mcp MCP server connects AI agents with n8n workflow data and provides focused tools for creation, validation, comparison, and troubleshooting. Its stateless capabilities do not require a running n8n instance: an agent can generate workflow JSON from a plain-language request, produce a TypeScript `INodeType` file for a custom n8n package, lint workflow JSON, compare two workflows, explain a failed execution, create a node-specific replay workflow, or produce an execution timeline.

The server also exposes operations for live n8n instances. Agents can list workflows with filters, retrieve a workflow by ID, create a workflow, change its active state, and browse executions. These live operations require n8n API access.

## How it works

The n8n-mcp MCP server exposes tools through MCP using dot-notation groups such as `workflow.*`, `node.*`, and `execution.*`. Each tool provides an output schema and MCP annotations describing properties such as read-only, destructive, or idempotent behavior.

For generation, the agent supplies a natural-language description and receives workflow JSON suitable for importing into n8n. The generator detects AI-agent requirements and can represent LangChain-related connections, including `ai_languageModel`, `ai_memory`, and `ai_tool`. Linting checks more than 20 conditions, including deprecated node types, missing AI Agent language models, webhook identifiers, IF node schema issues, and invalid connections across connection types.

Execution analysis accepts execution JSON. The explanation tool reports node-level findings and hints, while the timeline tool summarizes start times, durations, item counts, and errors. Replay builds a standalone workflow focused on a selected node. The diff tool identifies changes to nodes, connections, and settings.

## Setup and configuration

Install Node.js 20 or later, then install the package globally with `npm install -g @automatelab/n8n-mcp`, or launch it with `npx -y @automatelab/n8n-mcp` from an MCP host configuration. Cursor and Claude Desktop examples are provided in the repository. The four stateless tools can run without environment variables.

Set `N8N_API_URL` and `N8N_API_KEY` to enable the live-instance tools. The API key is created in n8n under Settings, API, and Create API key. The repository also documents Docker, Claude Desktop DXT, Render, Railway, and Fly.io deployment options.

Runtime policies can restrict access without modifying the server. `N8N_MCP_READ_ONLY=1` disables workflow creation, activation, and node scaffolding. `N8N_MCP_DISABLED_TOOLS` prevents selected tools from registering, while `N8N_MCP_ALLOWED_WORKFLOW_IDS` and `N8N_MCP_ALLOWED_TAGS` limit which workflows the REST tools can access or list.

## Limitations and notes

The n8n-mcp MCP server does not require a live n8n instance for its stateless analysis and generation tools, but workflow listing, retrieval, creation, activation, and execution browsing depend on valid API configuration. Creating or activating workflows changes the connected n8n instance unless runtime restrictions disable those operations.

Tool names use dot-notation in the current release, replacing earlier `n8n_*` snake-case names. Existing prompts, scripts, or agent skills that reference the old names need updating. The repository includes example workflows for Stripe-to-Slack with Google Sheets and RSS-to-Discord, but importing them still happens through n8n's Import from File flow.

_Full upstream README: https://allmcps.com/mcp/n8n-mcp/readme_