n8n-MCP: giving Claude and Cursor structured knowledge of 3,430 n8n nodes

What n8n-MCP actually fixes about AI-assisted n8n building

An AI assistant writing an n8n workflow without ground truth invents parameter names. It will produce a Set node with a plausible-looking field that does not exist, or call an operation the node never had. The failure is quiet: the JSON looks like a workflow, and you only find out when it is imported and the node shows errors. n8n-MCP addresses that by serving the assistant structured node data over the Model Context Protocol instead of relying on whatever the model memorised during training. The README frames it as a bridge between n8n and AI models, and the numbers it publishes are specific: 3,430 nodes (842 core, 2,588 community, of which 2,163 are verified), node properties at 99% coverage, node operations at 66.5%, and documentation at 86%. It is aimed at people who already use an MCP-capable client and want to describe a workflow in prose rather than assemble nodes by hand. It also lists 267 AI-capable tool variants and 2,352 workflow templates.

The knowledge layer: nodes, operations, docs and templates as separate resources

The architecture is a lookup service, not a code generator. n8n-MCP holds indexed data about n8n nodes and exposes it through MCP tools that the assistant calls during a conversation. Four data sets are described in the README. Node properties carry the schemas, at the coverage figure above. Node operations describe the actions a node can perform, and this is the weakest of the four at 66.5%, which means roughly a third of operations are not represented and an assistant working from this server alone may still guess. Documentation is pulled from official n8n docs at 86% coverage, including the AI nodes. Templates are a separate corpus: 2,352 workflows with what the README calls 99.96% AI metadata coverage, plus 156 ranked configurations extracted from popular templates. The ranking matters more than the count. A template library without ranking gives the assistant no way to choose between near-identical examples, and the README's phrase "ranked configurations" is the mechanism that makes the template tool useful rather than noisy. Community nodes are searchable through a source filter, which is how the 2,163 verified integrations are distinguished from the rest.

Getting it running: hosted dashboard versus self-hosting

There are two paths, and the README pushes the hosted one first. The quick start is dashboard.n8n-mcp.com, described as free at 100 tool calls per day with no installation and no configuration; you sign up, take an API key, and point your MCP client at it. The self-hosting route is documented separately in docs/SELF_HOSTING.md, which the README says covers npx, Docker, Railway and local installation. A published image exists at ghcr.io/czlonkowski/n8n-mcp, and there is a Railway deploy button. Connecting to a live n8n instance is a third layer, covered in docs/N8N_DEPLOYMENT.md, and it introduces the config keys that matter. N8N_API_URL and N8N_API_KEY are the base pair. If your n8n sits behind Cloudflare Access, N8N_CF_CLIENT_ID and N8N_CF_CLIENT_SECRET are sent as CF-Access-Client-Id and CF-Access-Client-Secret headers on API requests, version and health probes, and webhook executions. The README notes a deliberate restriction: the token is confined to the N8N_API_URL origin, so webhook calls to a different host (a split WEBHOOK_URL origin) do not receive it. That is a sensible boundary and worth knowing before you debug a 403 on a webhook. A fourth key, N8N_MCP_ACCESS_TOKEN, is separate from N8N_API_KEY and comes from n8n Settings, Instance-level MCP, where MCP status must be set to Enabled. It is required only for n8n_manage_agents, n8n_explore_node_resources and the project fallback in n8n_list_catalog. The README states plainly that instances serving MCP from a split host via N8N_MCP_BASE_URL are not supported. IDE-specific setup lives in separate documents for Claude Code, VS Code with Copilot, Cursor, Windsurf, Codex and Antigravity.

Two API keys, one endpoint assumption, and the split-host limitation

The most concrete constraint is the endpoint derivation. N8N_MCP_ACCESS_TOKEN is used against an MCP endpoint derived from N8N_API_URL. If your n8n serves its instance-level MCP from a different host, there is a documented N8N_MCP_BASE_URL variable but the README says that configuration is not supported. That is a hard boundary, not a rough edge, and it rules the feature out for split-host deployments. The second constraint is the distinction between the two secrets. N8N_API_KEY and N8N_MCP_ACCESS_TOKEN are different values with different sources, and the README advises storing them the same way, which implies treating both as credentials rather than one as a lesser token. Anyone who assumes a single key covers both the REST API and the instance-level MCP tools will find that n8n_manage_agents and n8n_explore_node_resources simply do not work. Beyond configuration, the operation coverage gap is the limitation that will bite during real use. An assistant that can see 99% of node properties but only 66.5% of operations is well equipped to describe a node and less well equipped to invoke the right action on it.

The safety warning is the honest part of the README

The README opens its practical guidance with a warning in capitals: never edit production workflows directly with AI. It then lists four steps, make a copy before using AI tools, test in a development environment, export backups, and validate before deploying. The stated reason is that AI results can be unpredictable. This is unusual candour for a project page, and it should be read as the author's own assessment of the tool's reliability rather than boilerplate. It also tells you what class of product this is. A server that only served accurate schemas would not need a production warning; a server whose output is fed to an assistant that then writes workflow JSON does. The mitigation is procedural, not technical. You bring your own. The companion n8n-skills repository is referenced as a way to teach the assistant to build production-ready workflows, which is a prompt-level intervention rather than a guardrail.

How it differs from pasting n8n docs into a prompt

The obvious alternative is manual context: copy the relevant node documentation into the conversation, or rely on the model's training data. The difference is retrieval versus recall. A pasted doc block is static and scoped to whatever you thought to include; the model cannot ask for the Set node's operation list halfway through generating a workflow. n8n-MCP inverts that, letting the assistant request node properties, operations, docs or templates as the need appears, across 3,430 nodes rather than the handful you pasted. The template corpus is the part that has no manual equivalent at 2,352 entries. The trade-off is a dependency. Manual context works offline, needs no API key, and cannot rate-limit you. The hosted tier is capped at 100 tool calls per day on the free plan, and a workflow-building session with parallel validation calls will consume that faster than the number suggests. Self-hosting removes the cap and moves the maintenance onto you. A second alternative worth naming is n8n's own instance-level MCP server, which n8n-MCP partially wraps through N8N_MCP_ACCESS_TOKEN for agent management and node resource exploration. Those are different products with overlapping surface: n8n's server exposes your instance, n8n-MCP exposes knowledge about nodes. The README treats them as complementary, and the configuration supports that reading.

Maintenance, version drift and what the MIT licence leaves you

The release cadence is brisk: v2.100.0 landed on 2026-11-03, with v2.99.2 on 2026-10-27 and v2.99.1 on 2026-10-25. Frequent releases are good for node coverage and awkward for anyone pinning a version, because the value of the tool is its currency against n8n's own releases. The README carries an n8n version badge, which is the compatibility target the project advertises; if your instance runs a different version, that is the first thing to check, since node schemas change between n8n releases and stale data is worse than no data because the assistant will trust it. The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. The hosted service's own terms are a separate question from the code licence. This is not legal advice; if you are embedding the server in a product, read the LICENSE file in the repository. Maintenance cost for self-hosters is the ongoing pull of new images or package versions plus the n8n compatibility check, and the README's sponsorship section states directly that maintaining the project competes with the author's paid work, which is a reasonable signal about the sustainability model you are relying on.

Editorial conclusion

Adopt n8n-MCP if you already drive Claude Code, Cursor, Windsurf or VS Code Copilot and want node schemas and templates in context rather than pasted docs. Do not adopt it if you expect it to manage workflows without configuring n8n API access, or if your n8n instance serves its instance-level MCP endpoint from a split host, which the README states is unsupported. Before wiring it into anything that touches production, verify your n8n version against the one the README's n8n badge references, confirm whether you need N8N_MCP_ACCESS_TOKEN in addition to N8N_API_KEY, and check the operation coverage figure against the specific nodes your workflows use.

Frequently asked questions

Official sources

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