Skip to content
Get packs

Guide · Open source

How to use n8n-mcp: setup and connect to Claude, Cursor and more

Updated · written with AI from the project's own documentation and checked against our catalogue data

n8n-MCP is a Model Context Protocol server that sits between AI coding assistants, such as Claude Desktop, Claude Code, Cursor or Windsurf, and n8n, the workflow automation platform. It gives the assistant structured access to n8n node documentation, properties, operations, templates and examples so it can design and check workflows more accurately. This guide explains who it suits, how to get started with the hosted dashboard or a self-hosted install, and how to connect it to your editor safely.

n8n-MCPczlonkowski/n8n-mcp · ★ 23.2k · MIT

Quick start

  1. 1Decide hosted or self-hosted. Use the hosted dashboard for the quickest start, or the Self-Hosting Guide if you want to run it yourself.
  2. 2Get your API key. On the hosted dashboard, sign up and get your API key.
  3. 3Clone the repository. Run git clone https://github.com/czlonkowski/n8n-mcp to get the source.
  4. 4Open your editor setup guide. Follow the guide for Claude Code, Cursor, Windsurf or VS Code to connect the MCP server.
  5. 5Connect your n8n instance if needed. Add your n8n API key, and Cloudflare or instance-level MCP variables only if your setup requires them.
  6. 6Work on a copy. Ask the assistant to draft or check a workflow on a copy, then test and back up before touching production.

Who should use n8n-MCP?

n8n-MCP is built for people who already use n8n and want an AI assistant to draft or check workflows. It is also useful for developers who want n8n knowledge available inside Claude Code, Cursor, Windsurf or VS Code.

It only helps with n8n workflows. If you do not use n8n, it will not be useful to you.

Choose between the hosted dashboard and self-hosting

The README describes two routes. The fastest is the hosted dashboard at dashboard.n8n-mcp.com, which has a free tier of 100 tool calls per day. You sign up, get an API key and connect your MCP client.

If you prefer to run it yourself, the self-hosting guide covers npx, Docker, Railway and a local installation.

  • Hosted: no infrastructure to manage, with usage limited by the free tier described in the README.
  • Self-hosted: npx, Docker, Railway or a local install, documented in the Self-Hosting Guide.

Install n8n-MCP from the repository

The README's install instruction starts by cloning the repository from GitHub. The project is written in TypeScript and published under the MIT licence. Node.js is a prerequisite; the README excerpt does not specify a version, so check the full README before installing.

  • Install Node.js first.
  • Clone the repository from the czlonkowski/n8n-mcp GitHub page.
git clone https://github.com/czlonkowski/n8n-mcp

Connect it to your AI editor

n8n-MCP lists setup guides for several tools. Pick the one that matches your editor and follow its page for the exact configuration.

  • Claude Code: Claude Code setup guide
  • Visual Studio Code: VS Code project setup guide
  • Cursor: Cursor setup guide
  • Windsurf: Windsurf setup guide, including project rules
  • Codex and Antigravity: their own setup guides

Connect to your own n8n instance (optional)

Without an n8n instance or API key, the tool gives the AI knowledge about nodes and templates but cannot act on your own n8n. To let it work with your instance, you provide an n8n API key.

If your n8n sits behind Cloudflare Access, set N8N_CF_CLIENT_ID and N8N_CF_CLIENT_SECRET. These are sent only to the N8N_API_URL origin, so webhook calls to a different host do not receive the token.

To use the instance-level MCP tools, set N8N_MCP_ACCESS_TOKEN from n8n Settings, then Instance-level MCP. It is a separate secret from N8N_API_KEY.

  • N8N_CF_CLIENT_ID: Cloudflare Access Client ID
  • N8N_CF_CLIENT_SECRET: Cloudflare Access Client Secret
  • N8N_MCP_ACCESS_TOKEN: MCP API key for instance-level MCP

Protect your production workflows

The README's safety warning is clear: never edit production workflows directly with AI. Work on a copy, test in a development environment, export backups and validate changes before they reach production.

AI results can be unpredictable, so treat generated workflows as drafts to review.

  • Make a copy of your workflow before using AI tools.
  • Test in a development environment first.
  • Export backups of important workflows.
  • Validate changes before deploying to production.

What people use it for

  • Drafting a new n8n workflow from a description, using node documentation and templates.
  • Checking an existing workflow for node configuration problems before deploying it.
  • Finding n8n nodes and their properties while writing workflows in Cursor or Claude Code.
  • Searching the library of workflow templates as a starting point.
  • Connecting an assistant to an n8n instance that sits behind Cloudflare Access.

Frequently asked questions

Is n8n-mcp free?

The project is released under the MIT licence. The README also describes a hosted dashboard with a free tier of 100 tool calls per day. Check the dashboard for any limits beyond that.

What do I need to run n8n-mcp?

You need Node.js, which the README excerpt does not give a version for. To act on your own n8n, you also need an n8n instance and an API key.

Which AI tools does n8n-mcp work with?

The README lists Claude Desktop, Claude Code, Cursor, Windsurf, Visual Studio Code, Codex and Antigravity, with a setup guide for each.

Can I self-host n8n-mcp?

Yes. The README points to a Self-Hosting Guide covering npx, Docker, Railway and local installation.

Is it safe to let AI edit my n8n workflows?

The README warns against letting AI edit production workflows directly. Copy the workflow, test it, export backups and validate changes before deploying.

How is n8n-mcp different from n8n's own AI features?

n8n-MCP is a separate server that gives external AI assistants knowledge of n8n nodes and templates. The n8n platform itself (n8n-io/n8n) has its own AI features built in.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

n8n-MCP suits people who already use n8n and want an AI assistant in their editor to draft or check workflows, especially if the hosted free tier is enough to start. If you do not use n8n, or you need a fully managed service without any setup, it is not the right fit, and you may prefer n8n's own built-in AI features.

Install options & downloads