n8n-MCP: Connecting AI Assistants to n8n Workflow Documentation

What n8n-MCP Does and Who It Is For

n8n is a workflow automation platform with over 2,864 nodes covering 836 core integrations and 2,028 community packages. Each node has its own parameter schema, required fields, and operation set. Keeping all of that in an AI model's context window is impractical. n8n-MCP solves this by running as a Model Context Protocol server that AI assistants query on demand. When Claude or Cursor needs to know the correct parameters for a Slack node, it calls the MCP server instead of guessing.

The primary audience is engineers who write n8n workflows with AI assistance inside Claude Desktop, Claude Code, Cursor, Windsurf, VS Code with GitHub Copilot, Codex, or Antigravity. The server can also connect to a live n8n instance through its API, which unlocks 16 additional management tools for listing, creating, and modifying workflows directly.

Node Coverage: What the Server Knows and What It Does Not

The README documents the coverage figures: 99% of nodes have detailed property schemas, 66.5% have operation definitions, and 86% have documentation from official n8n docs. The server ships 2,352 workflow templates with 99.96% AI metadata coverage, plus 156 ranked configurations extracted from those templates as real-world examples. There are 267 AI-capable tool variants with full documentation.

Community nodes (2,028 of the 2,864 total, with 1,674 verified) are searchable with a source filter.

Coverage gaps matter in practice. A node with no operation definition means the AI can see its properties but cannot confirm which operation names are valid at runtime. The README's Claude Project Setup instructions show a two-level validation strategy: run validate_node with mode set to minimal first for required-field checking, then mode set to full with profile set to runtime before building. The code snippet in the README shows the difference in practice:

// FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}

// WORKS - all parameters explicit
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}

The node data lives in a SQLite database. The path is controlled by NODE_DB_PATH, defaulting to ./data/nodes.db locally and /app/data/nodes.db inside Docker. REBUILD_ON_START controls whether the database rebuilds on each container restart.

How to Install n8n-MCP and Run It for the First Time

The fastest path is the hosted dashboard at dashboard.n8n-mcp.com, which requires no local setup. After signing up, you receive an API key and connect your MCP client to it. The free tier allows 100 tool calls per day.

For self-hosted deployment, the docker-compose.yml in the repository is the recommended starting point. The image is ghcr.io/czlonkowski/n8n-mcp:latest. AUTH_TOKEN is required for HTTP mode. Set MCP_MODE to http for remote and multi-client deployments, or stdio for a local single-process connection.

The .env.example file documents the key variables:

NODE_DB_PATH=./data/nodes.db
MCP_LOG_LEVEL=info
NODE_ENV=development
REBUILD_ON_START=false
MCP_MODE=stdio
PORT=3000

For HTTP mode, also set AUTH_TOKEN. After the container starts, the health endpoint at http://localhost:3000/health confirms the server is ready. The docker-compose.yml includes a healthcheck that polls that endpoint.

For Claude Code specifically, a setup guide is at docs/CLAUDE_CODE_SETUP.md. Cursor, Windsurf, and VS Code have equivalent guides at CURSOR_SETUP.md, WINDSURF_SETUP.md, and VS_CODE_PROJECT_SETUP.md.

Connecting to a Live n8n Instance

Without N8N_API_URL and N8N_API_KEY set, n8n-MCP operates in documentation-only mode. Adding those two variables enables 16 workflow management tools for listing, inspecting, creating, and modifying workflows on the connected instance.

If that n8n instance sits behind Cloudflare Access Zero Trust, two additional variables are needed:. The README names the two required variables as N8N_CF_CLIENT_ID and N8N_CF_CLIENT_SECRET.

The README is explicit about scope: those Cloudflare credentials are sent only to the N8N_API_URL origin. Webhook calls to a different host do not receive them.

The instance-level MCP integration, which enables n8n_manage_agents and n8n_explore_node_resources, requires a separate token: N8N_MCP_ACCESS_TOKEN, obtained from n8n Settings under Instance-level MCP. This is distinct from N8N_API_KEY. The full setup walkthrough is in docs/OFFICIAL_MCP_SETUP.md.

The README includes a hard warning: never edit production workflows directly with AI. The documented practice is to copy the workflow, make changes in a development environment, validate, and export a backup before deploying to production.

Limits and Cases Where n8n-MCP Is the Wrong Tool

Operation coverage is 66.5%, meaning roughly one in three nodes has no operation definitions. For those nodes, the AI can see parameter names but cannot confirm valid operation values. Generated workflows may fail at runtime until the operation field is corrected by hand.

The server has a memory limit of 512MB in the docker-compose.yml, with a 256MB reservation. Workflows with very large node counts or template lookups that pull many examples simultaneously can approach that ceiling.

Telemetry is enabled by default. The docker-compose.yml comment says: "Anonymous usage statistics are ENABLED by default. To opt-out, uncomment and set to 'true': N8N_MCP_TELEMETRY_DISABLED". Teams with strict data policies should set that before deployment.

n8n-MCP is not a general-purpose automation tool. Teams using Zapier, Make, or Temporal gain nothing from it. It also does not replace n8n's own UI for designing complex branching logic. The README also states that instances using a split N8N_MCP_BASE_URL are not supported by the instance-level MCP endpoint.

n8n-MCP Versus Pasting Node Docs Into Context Manually

The obvious alternative is pasting relevant n8n documentation into the AI's context by hand. That approach works for a single node but does not scale when a workflow touches ten or fifteen different nodes, each with dozens of parameters. It also goes stale as n8n ships new node versions.

n8n-MCP keeps its database synchronized with n8n releases and exposes on-demand lookup instead of bulk context injection. The trade-off is an additional service to run and keep alive. The hosted dashboard removes that operational burden but introduces a daily call limit on the free tier and a dependency on an external service.

The companion project n8n-skills (a separate repository by the same author) adds specialized Claude skill instructions for building production-ready workflows. It extends n8n-MCP rather than replacing the node documentation function.

Maintenance, Licensing, and Upgrade Cost

The repository is under the MIT license, which permits commercial use, modification, and redistribution. The last push was on 2026-09-27 and the most recent release is v2.90.0, published that same day. The project releases frequently: v2.88.0 and v2.89.0 both shipped on 2026-09-23.

renovate.json is present, indicating automated dependency updates. The Dockerfile contains an explicit note about a maintenance risk: the overrides block must stay synchronized with package.json, because n8n-workflow declares an exact zod peer dependency and a drift causes npm install to fail outright. Any new direct runtime dependency imported by src/ must also be added to the builder stage, or TypeScript compilation fails.

The README states the project started as a personal tool and that maintenance competes with the author's paid work. For teams that need a support commitment, the author's firm AiAdvisors offers n8n automation builds and operations.

Upgrade cost is low for the hosted dashboard. For self-hosted Docker, pulling a new image and restarting is the full procedure, though a database schema change requires REBUILD_ON_START=true on the first boot after upgrade.

Editorial conclusion

Engineers who regularly build n8n workflows with Claude Desktop, Claude Code, or Cursor will find n8n-MCP reduces node lookup friction, since the AI validates configurations against real schemas instead of guessing. It is not useful to teams that have no n8n instance, and it must not be pointed at production workflows directly. Before adopting it, decide between the hosted dashboard (dashboard.n8n-mcp.com, no infrastructure, 100 free calls per day) and self-hosted Docker, which requires AUTH_TOKEN and a persistent data volume for the SQLite database.

Frequently asked questions

Official sources

1. czlonkowski/n8n-mcp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases