← Back to Home

n8n-MCP + Claude Code Setup Guide: AI-Driven Workflow Automation

AI automationn8nClaude CodeMCPworkflow2026

n8n is an open-source workflow automation platform with 500+ nodes covering email, databases, AI, and API integrations. But configuring workflows manually is time-consuming — you need to memorize node names, configuration parameters, and expression syntax.

n8n-MCP is a Model Context Protocol server that gives Claude Code and other AI assistants comprehensive access to n8n's node documentation, properties, and operations. Once installed, you describe what you need in natural language and Claude Code can:

According to n8n community data, n8n-MCP (czlonkowski/n8n-mcp) has received 20.6k+ GitHub Stars as of 2026, with 154k weekly NPM downloads — making it one of the most popular n8n+AI integration solutions available.

---

Installation Steps

Step 1: Confirm Environment Requirements

n8n-MCP requires:

Step 2: Install n8n-mcp Package Globally

npm install -g n8n-mcp

Verify installation:

npx n8n-mcp --version

If network is slow, use a mirror:

npm install -g n8n-mcp --registry=https://registry.npmmirror.com

Step 3: Configure Claude Code MCP Settings

Find your Claude Code MCP configuration file, location depends on your OS:

Add the following to your config:

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "n8n-mcp", "server"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "your-n8n-api-key"
      }
    }
  }
}

How to get your n8n API key:

1. Open your n8n instance (default http://localhost:5678)

2. Go to Settings → API → Create API Key

3. Copy the generated key and replace "your-n8n-api-key" in the config

Step 4: Verify the Connection

Restart Claude Code (or start a new session), then test:

/mcp list

If you see n8n in the list, the MCP server is connected successfully.

You can also test directly in Claude Code:

Create a workflow using n8n-MCP: check Gmail every 5 minutes, and if there's a new email, send the subject and sender to a Slack channel

---

The 5 Real Configuration Pitfalls I Hit

Pitfall 1: Wrong N8N_HOST Address

**Error message**: After connecting n8n-MCP, Claude Code reports Connection refused to http://localhost:5678

**Root cause**: n8n is running on a remote server or Docker container, and localhost points to Claude Code's local machine — not where n8n actually runs.

Solution:

Verification method: Test from Claude Code's machine with curl:

curl http://your-N8N_HOST/api/v1/users/me \
  -H "X-N8N-API-KEY: your-api-key"

If it returns user info, the connection is working.

---

Pitfall 2: API Key Insufficient Permissions

**Error message**: Claude Code reports Forbidden - API key does not have the required scope when creating workflows

Root cause: n8n API keys have read-only permission by default. Creating workflows requires write permissions.

Solution:

1. In n8n, go to Settings → API

2. Edit existing API Key or create a new one

3. Ensure these permissions are checked: workflow:read, workflow:write, execution:read

4. Update the N8N_API_KEY in your Claude Code config

Minimum permissions n8n-MCP needs:

---

Pitfall 3: n8n Version Incompatibility

**Error message**: n8n-mcp: server error - n8n instance is too old

Root cause: Some n8n-MCP features depend on newer n8n REST API versions. Old n8n versions (like v0.x) don't support them.

Solution:

Check your n8n version:

# Docker method
docker exec  n8n info | grep Version

# Source method
cd /path/to/n8n && npm info n8n version

Recommended to use n8n v1.0+. If version is too old, upgrade:

# Docker upgrade
docker pull n8nio/n8n:latest
docker-compose up -d

# Source upgrade
git pull origin master
npm install

---

Pitfall 4: Claude Code Doesn't Recognize MCP Tools

Symptom: Config file is correct but Claude Code says "I don't have access to any n8n tools"

Root cause: Claude Code's MCP configuration is project-level, not global. You need to configure it separately for each project.

Solution:

1. Make sure the config file is in the correct project directory:

   ls ~/.claude/projects/
   # Find your project name, like default, my-project, etc.

2. Or create .mcp.json in your project root (not under ~)

3. Restart Claude Code to load new config:

   # Exit current Claude Code session
   # Start new session with project specified
   claude --project your-project-name

---

Pitfall 5: Docker Network Isolation Causes MCP Connection Failure

**Error message**: n8n runs in Docker, Claude Code reports ECONNREFUSED

**Root cause**: Docker's default network mode is bridge, and localhost points to the container interior, not the host machine.

Solution:

Option A: Use host.docker.internal (recommended)

{
  "env": {
    "N8N_HOST": "http://host.docker.internal:5678"
  }
}

Option B: Custom Docker network

# docker-compose.yml
services:
  n8n:
    networks:
      - n8n-network

networks:
  n8n-network:
    driver: bridge

Then set N8N_HOST to http://n8n:5678 (service name)

Option C: Expose ports (simple but less secure)

# docker-compose.yml
ports:
  - "5678:5678"

Then set N8N_HOST to http://your-server-IP:5678

---

Complete n8n-MCP + Claude Code Configuration Template

Save this to your project root directory as .mcp.json:

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "n8n-mcp", "server"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "nta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "N8N_LOG_LEVEL": "debug",
        "N8N_PROTOCOL": "http"
      }
    }
  }
}

Configuration field reference:

FieldDescriptionDefault
N8N_HOSTn8n instance addresshttp://localhost:5678
N8N_API_KEYAPI key from n8n Settings(required)
N8N_LOG_LEVELLog level: debug/info/warninfo
N8N_PROTOCOLProtocol: http or httpshttp

---

Practical Examples: Creating Your First n8n Workflow with Claude Code

After starting Claude Code, try these natural language commands:

Example 1: Gmail to Slack notification workflow

Create an n8n workflow:

Example 2: Database backup workflow

Create a workflow with n8n:

Example 3: Debug existing workflow

My n8n workflow "gmail-slack-forward" failed execution.
Help me check the last 5 execution records, find the failure cause, and fix it

---

Advanced n8n-MCP Usage

Use n8n-skills to Improve Generation Quality

The n8n community provides dedicated Claude Code Skills (czlonkowski/n8n-skills), which significantly improve generated workflow quality when installed:

git clone https://github.com/czlonkowski/n8n-skills.git
# Copy skills content to your Claude Code skills directory

n8n-skills includes 7 specialized skills:

Custom MCP Server Startup Parameters

For more granular control, you can call the server directly instead of using npx:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/n8n-mcp/dist/server.js"],
      "env": {
        "N8N_HOST": "https://your-n8n.example.com",
        "N8N_API_KEY": "nta_xxx",
        "NODE_ENV": "production"
      }
    }
  }
}

---

Troubleshooting Checklist

When encountering problems, check in order:

1. **Is n8n running?** curl http://localhost:5678 returns n8n page

2. **Is API key correct?** Access http://localhost:5678/api/v1/users/me directly in browser with API Key

3. Is port accessible? Use telnet or curl from Claude Code's machine to test n8n address

4. **Is MCP config loaded?** Start a new Claude Code session and type /mcp list to confirm n8n is in the list

5. Is Node.js version sufficient? 18.0+ required, older versions will cause syntax errors

---

When to Use and When Not to Use

Good fit for n8n-MCP:

Not suitable:

---

Summary

n8n-MCP combines Claude Code's natural language capabilities with n8n's 500+ workflow nodes, letting you build automation processes through conversation. The installation itself isn't complicated, but it's easy to hit pitfalls in network configuration, permissions, and version compatibility.

Core configuration is just 3 points:

1. N8N_HOST must have the correct address (watch out for Docker networking)

2. N8N_API_KEY permissions must include workflow read/write

3. Config file must be in the correct project directory

Recommended resources:

👉 Start your AI workflow automation journey: MiniMax Token Subscription Platform

---



**Book I recommend**: WordPress Plugin Development — Learn how to build WordPress plugins including workflow automation integrations.

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

DigitalOcean Cloud Vultr VPS 🏠 Amazon Best Sellers 📱 Amazon Devices 🔧 Amazon Renewed 🏠 Home Appliances 🎮 Apps & Games 📚 Books 💊 Health & Home 🎬 Movies & TV ⚽ Sports & Outdoors 🎯 Video Games 💻 Computers ⭐ MiniMax Token Plan
← Back to Home