n8n's MCP server lets Claude Code build, test, and iterate on automation workflows without leaving your terminal. Here's how to set it up and use it.
What the n8n MCP Server Actually Does #
If you’ve been building automation workflows in n8n, you already know the loop: open the browser, drag nodes around, wire connections, test, tweak, test again. It’s visual and approachable — but it’s slow when you’re iterating fast.
The n8n MCP server changes that. By connecting n8n to Claude Code via the Model Context Protocol (MCP), you can create, update, test, and manage n8n workflows directly from your terminal using plain language. Claude Code reads your workflow state, makes changes, and triggers executions — all without you leaving your editor or opening a browser tab.
This guide covers what the n8n MCP server is, how to get it running with Claude Code, and how to use it effectively for building and editing automation workflows.
Understanding the Stack: n8n, MCP, and Claude Code #
Before getting into setup, it helps to understand what’s actually happening when these three tools work together.
What is n8n?
n8n is an open-source workflow automation platform. It lets you connect apps and services using a node-based visual editor — think Zapier, but self-hostable, more flexible, and with support for custom code. Workflows in n8n are JSON objects under the hood, which matters for how the MCP server interacts with them.
What is MCP?
#
Plans first. Then code.
Remy writes the spec, manages the build, and ships the app.
The Model Context Protocol (MCP) is a standard developed by Anthropic that defines how AI models connect to external tools, data sources, and APIs. An MCP server exposes a set of typed tools — functions with defined inputs and outputs — that a compatible AI client can call. When an AI assistant uses an MCP server, it’s not just browsing the web; it’s making structured calls to specific tools and getting structured responses back.
What is Claude Code?
Claude Code is Anthropic’s terminal-based AI coding assistant. It operates in your shell, can read and write files, run commands, and — crucially — talk to MCP servers. Unlike a chat interface, Claude Code is designed for agentic, multi-step work. It can reason about a problem, take action, observe the result, and iterate.
Put these three together: Claude Code calls the n8n MCP server, which talks to your n8n instance via its REST API. You describe what you want in plain language, and Claude Code handles the workflow JSON.
Prerequisites #
Before you set anything up, make sure you have the following in place:
A running n8n instance— local (vianpx n8n
or Docker) or self-hosted. Cloud-hosted n8n (n8n.cloud) also works, but you’ll need API access enabled.An n8n API key— generate this in your n8n instance under** Settings → API → Create API Key**.** Claude Code installed**— you can install it globally withnpm install -g @anthropic-ai/claude-code
. You’ll also need an Anthropic API key.Node.js 18+— required to run the MCP server vianpx
.Basic familiarity with your terminal— you don’t need to know how to code, but you should be comfortable running commands.
Setting Up the n8n MCP Server #
Step 1: Enable the n8n API
In your n8n instance, navigate to Settings → n8n API. If the API isn’t already enabled, turn it on. Then create a new API key and copy it — you won’t see it again after leaving the page.
Your n8n API base URL will follow this format:
http://localhost:5678/api/v1
If you’re running n8n on a different port or a remote server, adjust accordingly.
Step 2: Configure Claude Code to Use the n8n MCP Server
Claude Code manages MCP servers through a configuration file. You can add the n8n server using the CLI:
claude mcp add n8n-server \
-e N8N_API_URL=http://localhost:5678/api/v1 \
-e N8N_API_KEY=your-api-key-here \
-- npx -y @n8n/mcp-server
This registers the n8n MCP server under the name n8n-server
. The -e
flags pass your API credentials as environment variables. The --
separates the Claude Code arguments from the command used to launch the server.
Alternatively, you can edit the configuration file directly. The MCP config lives at ~/.claude/claude_desktop_config.json
(or the equivalent path for your OS). Add your server to the mcpServers
block:
{
"mcpServers": {
"n8n": {
"command": "npx",
"args": ["-y", "@n8n/mcp-server"],
"env": {
"N8N_API_URL": "http://localhost:5678/api/v1",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
Save the file and restart Claude Code.
Step 3: Verify the Connection
Start a Claude Code session:
claude
Then ask it to confirm the connection is working:
List all my n8n workflows.
If the setup is correct, Claude Code will call the list_workflows
tool and return the workflows in your n8n instance. If you see an error, double-check your API URL (make sure it ends with /api/v1
) and confirm the API key is valid.
Step 4: Understanding What Tools Are Available
Other agents ship a demo. Remy ships an app. #
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
The n8n MCP server exposes a specific set of tools that Claude Code can call. Knowing what’s available helps you write better prompts. The core tools include:
— Returns all workflows in your n8n instance with their IDs, names, and active status.list_workflows
— Fetches the full JSON definition of a specific workflow by ID.get_workflow
— Creates a new workflow from a JSON definition.create_workflow
— Updates an existing workflow’s nodes, connections, or settings.update_workflow
— Toggles a workflow’s active state.activate_workflow
/deactivate_workflow
— Triggers a manual execution of a workflow.execute_workflow
— Shows execution history for a workflow.list_executions
— Retrieves the full log and output of a specific execution.get_execution
— Removes a workflow permanently.delete_workflow
Claude Code decides which tools to call based on your instructions. You don’t need to specify which tool to use — just describe what you want.
Building Workflows with Claude Code #
Starting from Scratch
The fastest way to build a new workflow is to describe it in plain language. Claude Code will construct the workflow JSON, call create_workflow
, and confirm once it’s created.
Example prompt:
Create an n8n workflow that:
1. Triggers on a webhook POST request
2. Parses the incoming JSON for a "customer_email" field
3. Sends a confirmation email using the Gmail node
4. Returns a 200 response
Name it "Customer Confirmation Webhook"
Claude Code will:
- Build the appropriate node definitions (Webhook trigger, Set node for parsing, Gmail node, Respond to Webhook node)
- Wire the connections between them
- Call
create_workflow
to push it to n8n - Report the workflow ID
You can then open n8n in your browser to verify it looks right — or stay in the terminal and keep iterating.
Providing Context for Better Results
The more context you give Claude Code, the more accurate the workflow it creates. Instead of generic descriptions, be specific:
- Name the nodes you expect (Gmail, Slack, HTTP Request, Airtable)
- Specify data transformations (e.g., “extract the first item from the array”)
- Mention error handling requirements
- Describe the expected payload structure if using a webhook trigger
If you’re connecting to a service that requires credentials, Claude Code will create the node with credential placeholders — you’ll need to add the actual credentials in the n8n UI.
Building from an Existing Workflow Template
If you already have a workflow you want to adapt, start by fetching it:
Get the workflow with ID 47 and show me its structure.
Claude Code will retrieve the JSON and summarize the node structure. You can then ask for modifications:
Add a Filter node after the HTTP Request node that only passes through items where the "status" field equals "active". Then update the workflow.
This is much faster than navigating the canvas manually when you know what change you need.
Editing and Iterating on Workflows #
Making Targeted Changes
You don’t have to rebuild a workflow from scratch to make changes. Claude Code can surgically update specific nodes, add new branches, or restructure connections.
Some examples of targeted edits:
In workflow 47, update the Slack node to post to the #alerts channel instead of #general.
Add error handling to workflow 23: if the HTTP Request node fails, send a notification to our Slack #errors channel and deactivate the workflow.
Rename workflow 15 to "Lead Sync - v2" and add a note to the trigger node explaining what data format it expects.
Coding agents automate the 5%. Remy runs the 95%. #
The bottleneck was never typing the code. It was knowing what to build.
Claude Code reads the current workflow state before making changes, so it’s not working blind — it pulls the live JSON, modifies it, and pushes the update.
Testing Workflows in the Terminal
One of the most useful things about this setup is the ability to trigger test executions and inspect results without touching the browser.
To test a workflow:
Execute workflow 47 and show me the output of each node.
Claude Code calls execute_workflow
, waits for completion, then calls get_execution
to fetch the full execution log. You’ll see the input and output data for each node, which makes debugging straightforward.
If something fails:
The last execution of workflow 47 failed. Get the execution details and tell me which node failed and why.
Claude Code will retrieve the execution, identify the failure point, and explain what went wrong — often suggesting a fix in the same response.
Iterative Development Loop
The real advantage here is speed of iteration. A typical loop looks like this:
- Describe a change in plain language
- Claude Code updates the workflow
- You trigger a test execution
- Claude Code retrieves and interprets the results
- You describe the next change
This loop can run entirely in the terminal. For complex workflows, you might do a dozen iterations in the time it would take to make three changes in the visual editor.
Common Patterns and Use Cases #
Automated Reporting Pipeline
A good candidate for the terminal-first workflow approach is a data reporting pipeline — pulling data from a source, transforming it, and delivering it somewhere.
Create a workflow that runs every Monday at 9am, fetches data from our Postgres database using this query: "SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '7 days'", formats it as a CSV, and emails it to reports@company.com.
Claude Code will build the Schedule Trigger, Postgres, Spreadsheet File, and Gmail nodes, wire them together, and create the workflow. You can then test the database connection and adjust the query as needed.
Webhook-to-CRM Integration
Build a workflow that listens for webhooks from our form tool, maps the incoming fields to HubSpot contact properties (first_name → firstname, email → email, company → company), creates or updates the contact in HubSpot, and sends a Slack message to #sales with the contact's name and company.
Debugging a Broken Workflow
Workflow 31 has been failing for the past two days. List its recent executions, find the failed ones, and tell me what error is occurring.
Claude Code will call list_executions
filtered to failed runs, pull the details, and give you a diagnostic summary.
Common Mistakes and How to Avoid Them #
Not specifying the workflow ID when you have many workflows. If you have dozens of workflows, Claude Code might not know which one you mean. Reference workflows by name or ID explicitly.
Expecting credentials to be set automatically. The MCP server can create nodes that require credentials (Gmail, Slack, HubSpot), but it cannot store credentials for you. You’ll need to add these in the n8n UI after the workflow is created.
Day one: idea. Day one: app. #
Not a sprint plan. Not a quarterly OKR. A finished product by end of day.
Running test executions on active production workflows. Before testing, consider deactivating a workflow to avoid it firing real side effects while you’re iterating. Ask Claude Code to deactivate it first.
Forgetting to activate workflows after building them. Newly created workflows are inactive by default. If your workflow uses a scheduled trigger or webhook, ask Claude Code to activate it when you’re ready.
Making too many changes in one prompt. Break complex changes into smaller steps. Each step is a tool call with a specific result. Batching five unrelated changes into one prompt makes it harder to verify what worked.
Where MindStudio Fits for AI-Driven Automation #
The n8n + Claude Code approach is powerful, but it assumes you’re comfortable in a terminal environment and want to manage your own n8n instance. For teams that want to build AI-powered workflows without that infrastructure overhead — or that need agents capable of reasoning across multiple steps — MindStudio is worth looking at.
MindStudio is a no-code platform for building AI agents and automated workflows. You can connect 1,000+ business tools — HubSpot, Salesforce, Google Workspace, Slack, Airtable — through a visual builder, with access to 200+ AI models (Claude, GPT-4, Gemini, and more) without managing API keys or infrastructure.
What’s directly relevant here: MindStudio supports agentic MCP servers. You can expose your MindStudio agents as MCP servers, making them callable from Claude Code, LangChain, CrewAI, or any other MCP-compatible client. That means you can use Claude Code to trigger MindStudio agents the same way you’re triggering n8n workflows — extending what’s possible on both ends.
If you’re building workflows that involve complex AI reasoning (not just routing data between apps), MindStudio is better suited for it. The average agent build takes 15 minutes to an hour, and you can try it free at mindstudio.ai.
FAQ #
What is the n8n MCP server?
The n8n MCP server is a Model Context Protocol server that exposes n8n’s REST API as a set of typed tools. AI clients like Claude Code can use these tools to list, create, update, execute, and delete n8n workflows programmatically — without using the n8n visual editor.
Does the n8n MCP server work with self-hosted n8n?
Yes. The MCP server communicates with n8n via its REST API, which is available on both self-hosted and cloud-hosted n8n instances. You just need to provide the correct API base URL and a valid API key. For local instances, this is typically http://localhost:5678/api/v1
.
Can Claude Code create complex workflows with multiple branches?
Yes, but with some caveats. Claude Code can build workflows with conditional branches, parallel execution paths, and error handling nodes. The more detailed your description of the branching logic, the more accurate the output. For very complex workflows, building in stages (create the happy path first, then add error handling) tends to produce better results than describing everything at once.
Do I need to know n8n’s JSON format to use this?
How Remy works. You talk. Remy ships. #
No. Claude Code handles the workflow JSON internally. You describe what you want in plain language, and it translates that into the correct node definitions and connection structure. That said, having a basic understanding of how n8n nodes work (trigger nodes, action nodes, credentials) helps you write better prompts and catch mistakes.
What’s the difference between using the n8n MCP server and using n8n’s own AI features?
n8n has its own AI assistant built into the editor that can help you build workflows. The MCP server approach is different: it integrates n8n as a tool inside Claude Code’s agentic environment, which means Claude Code can manage workflows as part of a larger task — such as building a whole system that includes multiple workflows, code files, and configuration. The MCP approach is better for developers who are already using Claude Code as their primary tool.
Is this approach production-safe?
Be careful with test executions on active workflows that have real side effects (sending emails, creating CRM records, posting to Slack). Always review what Claude Code is about to do before confirming. For production workflows, it’s good practice to work on a duplicate first, test thoroughly, then swap it in.
Key Takeaways #
- The n8n MCP server connects Claude Code to your n8n instance, letting you build and manage workflows from the terminal using plain language.
- Setup requires a running n8n instance, an API key, and a few lines of configuration in Claude Code’s MCP settings.
- Claude Code can create new workflows, update existing ones, trigger test executions, and retrieve execution logs — handling the workflow JSON entirely.
- The terminal-based iteration loop is significantly faster than the visual editor for developers who know what they want to build.
- For teams who want AI-native workflow automation without managing n8n infrastructure, MindStudio offers a no-code alternative with native MCP server support.
If you’re already using Claude Code for development work, adding the n8n MCP server is a low-effort setup that pays off quickly — especially if you’re regularly building or maintaining complex automation workflows. Give it a try, and if you hit friction with the infrastructure side, MindStudio is a solid place to look for a more managed approach.