n8n-setup

# n8n MCP Setup & Verification Configure and verify n8n MCP server connections for workflow development. --- ## Two MCP Server Types n8n provides two complementary MCP servers. Each serves a different purpose. ### External MCP (`n8n-mcp-external`) Third-party MCP server by czlonkowski. Optimized for workflow **development**. - **28 tools**: 7 core (`tools_documentation`, `search_nodes`, `get_node`, `validate_node`, `validate_workflow`, `search_templates`, `get_template`) that work offline, plus 21 `n8n_*` tools that talk to your instance (Public API, and — with `N8N_MCP_ACCESS_TOKEN` — the instance-level MCP) - Installed via `npx n8n-mcp` - Communicates over **stdio** transport - Best for: building, editing, validating, and debugging workflows - Repository: https://github.com/czlonkowski/n8n-mcp **Key capabilities:** - Search and inspect ~840 built-in nodes plus verified and unverified community nodes (do not hard-code the count) - Validate node configurations against schemas - Create, read, update, delete workflows (JSON-based) - Deploy from the community template library - Manage credentials (create, update, delete, list schemas) - Audit instance security - Manage data tables, rows and columns - Auto-fix validation errors - Run workflows without an external trigger (`n8n_test_workflow` with `prepare` / `pinned` / `direct`) - Manage n8n Agents (`n8n_manage_agents`, Preview) > `npx n8n-mcp` always pulls the latest release. For a reproducible setup pin it: `npx n8n-mcp@<version>` (find the current one with `npm view n8n-mcp version`). ### Native MCP (`n8n-native-mcp`) Official MCP server built into n8n. Optimized for SDK-based workflow **creation**, publishing and Agents. - **54 tools** on n8n 2.41 (the set depends on the n8n version): workflow builder, workflow management, executions and tests, versions, credentials (read-only), projects and folders, data tables, Agents - Built into n8n (no separate install) - Communicates over **HTTP** transport - Best for: creating workflows from TypeScript SDK code, atomic edits, testing, publishing, building n8n Agents - Needs n8n with instance-level MCP enabled — see the version table below **Key capabilities:** - Get the SDK reference, best practices per technique, and type definitions - Search and discover nodes with discriminators - Create workflows from TypeScript SDK code and validate it first - Edit workflows with atomic operations (`update_workflow`) - Execute (manual or production), test with pin data, read results - Publish/unpublish/archive, browse and restore version history - Search projects, folders and tags; manage data tables - Build, test and publish first-class n8n Agents (Preview) ### Minimum n8n versions | Capability | n8n | |-----------|-----| | Instance-level MCP | 2.2.0 | | Builder tools (create and edit workflows) | 2.13.0 | | Partial `update_workflow` (operations list) | 2.20.0 | | Connect dialog, OAuth, `/publish` routes | 2.33.0 | | Agents tools, renamed native tools, `n8n_test_workflow` `prepare`/`pinned`/`direct`, column actions | 2.34.0 | Agents are **Preview**. --- ## Environment Variables Set these at the **project level** (not plugin level). The plugin references them via `${VAR}` placeholders. ### For External MCP | Variable | Description | How to Generate | |----------|-------------|-----------------| | `N8N_API_URL` | n8n instance URL — root (`https://your-n8n.example.com`) or ending in `/api/v1`; both work | Your n8n deployment URL | | `N8N_API_KEY` | Public API key | n8n UI: Settings → n8n API → Create an API key | | `N8N_MCP_ACCESS_TOKEN` | *Optional.* The instance-level MCP access token. A separate secret from `N8N_API_KEY`; it unlocks `n8n_test_workflow` (`prepare`/`pinned`/`direct`), `n8n_manage_agents`, `n8n_explore_node_resources`, `n8n_workflow_versions` with `source: "native"`, the column actions of `n8n_manage_datatable`, and the MCP fallback of `n8n_list_catalog`. The endpoint is derived from `N8N_API_URL`. | n8n UI: Settings → Instance-level MCP → Connect → **API key** tab (n8n 2.33+; earlier versions show the token on the MCP settings page) | Optional extras: `N8N_CF_CLIENT_ID` / `N8N_CF_CLIENT_SECRET` (Cloudflare Access in front of n8n), `DISABLED_TOOLS` (comma-separated tool names to hide, for a read-only setup). ### For Native MCP | Variable | Description | How to Generate | |----------|-------------|-----------------| | `N8N_NATIVE_MCP_URL` | Full MCP endpoint URL (e.g., `https://your-n8n.example.com/mcp-server/http`) | n8n UI: Settings → Instance-level MCP → Connect → **Server URL** | | `N8N_MCP_TOKEN` | MCP access token (sent as a `Bearer` header) — the same kind of value as `N8N_MCP_ACCESS_TOKEN` | n8n UI: Settings → Instance-level MCP → Connect → **API key** tab | MCP access must be enabled first: **Settings → Instance-level MCP → Enable MCP access** (instance owner or admin). Each workflow you want the client to run or edit must also be switched on (**Available in MCP**, only for published workflows with a webhook, form, schedule or chat trigger) — see the **n8n-native-mcp** skill. ### Setting Environment Variables Store these in your shell profile or project-level `.env`: ```bash export N8N_API_URL="https://your-n8n.example.com" export N8N_NATIVE_MCP_URL="https://your-n8n.example.com/mcp-server/http" export N8N_API_KEY="your-api-key-here" export N8N_MCP_TOKEN="your-mcp-token-here" export N8N_MCP_ACCESS_TOKEN="your-mcp-token-here" # optional, see above ``` **Security note:** Never commit API keys or tokens to version control. Use environment variables or a secrets manager. ### OAuth instead of a token (native MCP) The Connect dialog recommends **OAuth** over a pasted token. Keep the server name `n8n-native-mcp` so that the tool names in these skills (`mcp__n8n-native-mcp__...`) resolve: ```bash claude mcp add --transport http n8n-native-mcp https://<n8n-host>/mcp-server/http ``` Then run `/mcp` in Claude Code, pick **n8n-native-mcp** and finish the sign-in in the browser. No `N8N_MCP_TOKEN` is needed in that case. (The OAuth login is an interactive step the user performs.) --- ## Project `.mcp.json` Configuration Create or update `.mcp.json` in your project root. ### External MCP Only (stdio) Use when you need workflow development tools — node search, validation, workflow CRUD, templates, credentials, audit. ```json { "mcpServers": { "n8n-mcp-external": { "command": "npx", "args": ["n8n-mcp"], "env": { "MCP_MODE": "stdio", "LOG_LEVEL": "error", "DISABLE_CONSOLE_OUTPUT": "true", "N8N_API_URL": "${N8N_API_URL}", "N8N_API_KEY": "${N8N_API_KEY}", "N8N_MCP_ACCESS_TOKEN": "${N8N_MCP_ACCESS_TOKEN:-}" } } } } ``` `${N8N_MCP_ACCESS_TOKEN:-}` keeps the token optional: with it unset the server starts and only the token-gated tools answer `NOT_CONFIGURED`. ### Native MCP Only (HTTP) Use when you need SDK-based workflow creation, testing, publishing and Agents. ```json { "mcpServers": { "n8n-native-mcp": { "type": "http", "url": "${N8N_NATIVE_MCP_URL}", "headers": { "Authorization": "Bearer ${N8N_MCP_TOKEN}" } } } } ``` ### Combined Configuration (Both Servers) Use when you need the full capability set — development tools from external plus SDK-based creation, testing and Agents from native. ```json { "mcpServers": { "n8n-mcp-external": { "command": "npx", "args": ["n8n-mcp"], "env": { "MCP_MODE": "stdio", "LOG_LEVEL": "error", "DISABLE_CONSOLE_OUTPUT": "true", "N8N_API_URL": "${N8N_API_URL}", "N8N_API_KEY": "${N8N_API_KEY}", "N8N_MCP_ACCESS_TOKEN": "${N8N_MCP_ACCESS_TOKEN:-}" } }, "n8n-native-mcp": { "type": "http", "url": "${N8N_NATIVE_MCP_URL}", "headers": { "Authorization": "Bearer ${N8N_MCP_TOKEN}" } } } } ``` --- ## Verification Steps After configuring `.mcp.json`, verify each server is operational. ### Verify External MCP **Step 1: Health check** Call `mcp__n8n-mcp-external__n8n_health_check`. Expected: `status` is `healthy` (`degraded` means the instance answers but something is off; `error` means the URL or key is wrong). The response also carries `mcpVersion`, `supportedN8nVersion`, `versionCheck` (`current`, `latest`, `upToDate`, `updateCommand`), `features` and `performance`. `n8nVersion` is usually **absent** — n8n stopped exposing its version to API clients in 1.119.0 and the response says so in `n8nVersionNote`. That is not an error and not worth retrying; probe capabilities by calling the API instead of comparing versions. With `N8N_MCP_ACCESS_TOKEN` set, an `officialMcp` block reports whether the instance-level MCP is reachable. If `status` is `error`, `N8N_API_URL` or `N8N_API_KEY` is wrong. `mode: "diagnostic"` adds debug detail. **Step 2: Test node search** Call `mcp__n8n-mcp-external__search_nodes` with `query: "webhook"`. Expected: a list of matching nodes including `n8n-nodes-base.webhook`. **Step 3: Test workflow listing** Call `mcp__n8n-mcp-external__n8n_list_workflows`. Expected: a list of existing workflows (may be empty on fresh instances). ### Verify Native MCP **Step 1: Search workflows** Call `mcp__n8n-native-mcp__search_workflows` with `limit: 1`. Expected: a preview list (may be empty on fresh instances). A result or an empty list without errors means the connection and the token work. This call returns previews of **every** workflow the user can see, whether or not it is exposed to MCP. **Step 2: Get SDK reference** Call `mcp__n8n-native-mcp__get_workflow_sdk_reference` with `section: "rules"`. Expected: the SDK rules. This confirms the builder tools are available (n8n 2.13+). **Step 3: Search nodes** Call `mcp__n8n-native-mcp__search_nodes` with `queries: ["webhook"]`. Expected: node search results with IDs and discriminators. ### Quick Verification Checklist | Check | Tool | Pass Condition | |-------|------|----------------| | External health | `n8n_health_check` | `status: "healthy"` | | External nodes | `search_nodes` | Returns node results | | External workflows | `n8n_list_workflows` | Returns list (no auth error) | | Native workflows | `search_workflows` | Returns list (no auth error) | | Native SDK | `get_workflow_sdk_reference` | Returns documentation | | Native nodes | `search_nodes` | Returns results with discriminators | --- ## Available Tools by Server ### External MCP Tools (28) | Tool | Purpose | |------|---------| | `tools_documentation` | Tool docs, AI agent guide (`topic: "ai_agents_guide"`), Code node guides | | `search_nodes` | Find nodes by keyword | | `get_node` | Get node details, docs, property search, versions | | `validate_node` | Validate node configuration | | `validate_workflow` | Validate a complete workflow JSON | | `search_templates` | Search community templates | | `get_template` | Get template details | | `n8n_health_check` | Verify connection to the n8n instance | | `n8n_create_workflow` | Create workflow from JSON | | `n8n_get_workflow` | Get workflow by ID (`full`, `details`, `structure`, `minimal`, `active`, `filtered`) | | `n8n_list_workflows` | List workflows | | `n8n_update_full_workflow` | Replace the entire workflow | | `n8n_update_partial_workflow` | Update specific nodes/connections (diff operations) | | `n8n_delete_workflow` | Delete workflow | | `n8n_validate_workflow` | Server-side validation of a deployed workflow | | `n8n_autofix_workflow` | Auto-fix validation errors | | `n8n_deploy_template` | Deploy template to the instance | | `n8n_test_workflow` | Run a workflow (HTTP trigger, or `prepare`/`pinned`/`direct` via the instance MCP) |