n8n-MCP

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 1,084 workflow automation nodes (537 core + 547 community).

Overview

n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:

• 📚 1,084 n8n nodes - 537 core nodes + 547 community nodes (301 verified)
• 🔧 Node properties - 99% coverage with detailed schemas
• ⚡ Node operations - 63.6% coverage of available actions
• 📄 Documentation - 87% coverage from official n8n docs (including AI nodes)
• 🤖 AI tools - 265 AI-capable tool variants detected with full documentation
• 💡 Real-world examples - 2,646 pre-extracted configurations from popular templates
• 🎯 Template library - 2,709 workflow templates with 100% metadata coverage
• 🌐 Community nodes - Search verified community integrations with source filter (NEW!)

⚠️ Important Safety Warning

NEVER edit your production workflows directly with AI! Always:

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

AI results can be unpredictable. Protect your work!

🚀 Quick Start

Option 1: Hosted Service (Easiest - No Setup!) ☁️

The fastest way to try n8n-MCP - no installation, no configuration:

👉 dashboard.n8n-mcp.com

• ✅ Free tier: 100 tool calls/day
• ✅ Instant access: Start building workflows immediately
• ✅ Always up-to-date: Latest n8n nodes and templates
• ✅ No infrastructure: We handle everything

Just sign up, get your API key, and connect your MCP client.

🏠 Self-Hosting Options

Prefer to run n8n-MCP yourself? Choose your deployment method:

Option A: npx (Quick Local Setup) 🚀

Get n8n-MCP running in minutes:

Prerequisites: Node.js installed on your system

# Run directly with npx (no installation needed!)
npx n8n-mcp

Add to Claude Desktop config:

⚠️ Important: The MCP_MODE: "stdio" environment variable is required for Claude Desktop. Without it, you will see JSON parsing errors like "Unexpected token..." in the UI. This variable ensures that only JSON-RPC messages are sent to stdout, preventing debug logs from interfering with the protocol.

Basic configuration (documentation tools only):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

Full configuration (with n8n management tools):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Note: npx will download and run the latest version automatically. The package includes a pre-built database with all n8n node information.

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after updating configuration - That's it! 🎉

Option B: Docker (Isolated & Reproducible) 🐳

Prerequisites: Docker installed on your system

📦 Install Docker (click to expand)

macOS:

# Using Homebrew
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop/

Linux (Ubuntu/Debian):

# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect

Windows:

# Option 1: Using winget (Windows Package Manager)
winget install Docker.DockerDesktop

# Option 2: Using Chocolatey
choco install docker-desktop

# Option 3: Download installer from https://www.docker.com/products/docker-desktop/

Verify installation:

docker --version

# Pull the Docker image (~280MB, no n8n dependencies!)
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

⚡ Ultra-optimized: Our Docker image is 82% smaller than typical n8n images because it contains NO n8n dependencies - just the runtime MCP server with a pre-built database!

Add to Claude Desktop config:

Basic configuration (documentation tools only):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Full configuration (with n8n management tools):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=https://your-n8n-instance.com",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

💡 Tip: If you're running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.

Note: The n8n API credentials are optional. Without them, you'll have access to all documentation and validation tools. With them, you'll additionally get workflow management capabilities (create, update, execute workflows).

🏠 Local n8n Instance Configuration

If you're running n8n locally (e.g., http://localhost:5678 or Docker), you need to allow localhost webhooks:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "-e", "WEBHOOK_SECURITY_MODE=moderate",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

⚠️ Important: Set WEBHOOK_SECURITY_MODE=moderate to allow webhooks to your local n8n instance. This is safe for local development while still blocking private networks and cloud metadata.

Important: The -i flag is required for MCP stdio communication.

🔧 If you encounter any issues with Docker, check our Docker Troubleshooting Guide.

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after updating configuration - That's it! 🎉

🔐 Privacy & Telemetry

n8n-mcp collects anonymous usage statistics to improve the tool. View our privacy policy.

Opting Out

For npx users:

npx n8n-mcp telemetry disable

For Docker users: Add the following environment variable to your Docker configuration:

"-e", "N8N_MCP_TELEMETRY_DISABLED=true"

Example in Claude Desktop config:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "N8N_MCP_TELEMETRY_DISABLED=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

For docker-compose users: Set in your environment file or docker-compose.yml:

environment:
  N8N_MCP_TELEMETRY_DISABLED: "true"

⚙️ Database & Memory Configuration

Database Adapters

n8n-mcp uses SQLite for storing node documentation. Two adapters are available:

1. better-sqlite3 (Default in Docker)

   • Native C++ bindings for best performance
   • Direct disk writes (no memory overhead)
   • Now enabled by default in Docker images (v2.20.2+)
   • Memory usage: ~100-120 MB stable

2. sql.js (Fallback)

   • Pure JavaScript implementation
   • In-memory database with periodic saves
   • Used when better-sqlite3 compilation fails
   • Memory usage: ~150-200 MB stable

Memory Optimization (sql.js)

If using sql.js fallback, you can configure the save interval to balance between data safety and memory efficiency:

Environment Variable:

SQLJS_SAVE_INTERVAL_MS=5000  # Default: 5000ms (5 seconds)

Usage:

• Controls how long to wait after database changes before saving to disk
• Lower values = more frequent saves = higher memory churn
• Higher values = less frequent saves = lower memory usage
• Minimum: 100ms
• Recommended: 5000-10000ms for production

Docker Configuration:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "SQLJS_SAVE_INTERVAL_MS=10000",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

docker-compose:

environment:
  SQLJS_SAVE_INTERVAL_MS: "10000"

💖 Support This Project

n8n-mcp started as a personal tool but now helps tens of thousands of developers automate their workflows efficiently. Maintaining and developing this project competes with my paid work.

Your sponsorship helps me:

• 🚀 Dedicate focused time to new features
• 🐛 Respond quickly to issues
• 📚 Keep documentation up-to-date
• 🔄 Ensure compatibility with latest n8n releases

Every sponsorship directly translates to hours invested in making n8n-mcp better for everyone. Become a sponsor →

Option C: Local Installation (For Development)

Prerequisites: Node.js installed on your system

# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

# 2. Test it works
npm start

Add to Claude Desktop config:

Basic configuration (documentation tools only):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

Full configuration (with n8n management tools):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Note: The n8n API credentials can be configured either in a .env file (create from .env.example) or directly in the Claude config as shown above.

💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.

Option D: Railway Cloud Deployment (One-Click Deploy) ☁️

Prerequisites: Railway account (free tier available)

Deploy n8n-MCP to Railway's cloud platform with zero configuration:

Benefits:

• ☁️ Instant cloud hosting - No server setup required
• 🔒 Secure by default - HTTPS included, auth token warnings
• 🌐 Global access - Connect from any Claude Desktop
• ⚡ Auto-scaling - Railway handles the infrastructure
• 📊 Built-in monitoring - Logs and metrics included

Quick Setup:

1. Click the "Deploy on Railway" button above
2. Sign in to Railway (or create a free account)
3. Configure your deployment (project name, region)
4. Click "Deploy" and wait ~2-3 minutes
5. Copy your deployment URL and auth token
6. Add to Claude Desktop config using the HTTPS URL

📚 For detailed setup instructions, troubleshooting, and configuration examples, see our Railway Deployment Guide

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after updating configuration - That's it! 🎉

🔧 n8n Integration

Want to use n8n-MCP with your n8n instance? Check out our comprehensive n8n Deployment Guide for:

• Local testing with the MCP Client Tool node
• Production deployment with Docker Compose
• Cloud deployment on Hetzner, AWS, and other providers
• Troubleshooting and security best practices

💻 Connect your IDE

n8n-MCP works with multiple AI-powered IDEs and tools. Choose your preferred development environment:

Claude Code

Quick setup for Claude Code CLI - just type "add this mcp server" and paste the config.

Visual Studio Code

Full setup guide for VS Code with GitHub Copilot integration and MCP support.

Cursor

Step-by-step tutorial for connecting n8n-MCP to Cursor IDE with custom rules.

Windsurf

Complete guide for integrating n8n-MCP with Windsurf using project rules.

Codex

Complete guide for integrating n8n-MCP with Codex.

Antigravity

Complete guide for integrating n8n-MCP with Antigravity.

🎓 Add Claude Skills (Optional)

Supercharge your n8n workflow building with specialized skills that teach AI how to build production-ready workflows!

Learn more: n8n-skills repository

🤖 Claude Project Setup

For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:

You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.

## Core Principles

### 1. Silent Execution
CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.

❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..."
✅ GOOD: [Execute search_nodes and get_node in parallel, then respond]

### 2. Parallel Execution
When operations are independent, execute them in parallel for maximum performance.

✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously
❌ BAD: Sequential tool calls (await each one before the next)

### 3. Templates First
ALWAYS check templates before building from scratch (2,709 available).

### 4. Multi-Level Validation
Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.

### 5. Never Trust Defaults
⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
ALWAYS explicitly configure ALL parameters that control node behavior.

## Workflow Process

1. **Start**: Call `tools_documentation()` for best practices

2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
   - `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - Smart filtering
   - `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - Curated by task
   - `search_templates({query: 'slack notification'})` - Text search (default searchMode='keyword')
   - `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - By node type

   **Filtering strategies**:
   - Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
   - By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
   - By time: `maxSetupMinutes: 15` for quick wins
   - By service: `requiredService: "openai"` for compatibility

3. **Node Discovery** (if no suitable template - parallel execution)
   - Think deeply about requirements. Ask clarifying questions if unclear.
   - `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
   - `search_nodes({query: 'trigger'})` - Browse triggers
   - `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes

4. **Configuration Phase** (parallel for multiple nodes)
   - `get_node({nodeType, detail: 'standard', includeExamples: true})` - Essential properties (default)
   - `get_node({nodeType, detail: 'minimal'})` - Basic metadata only (~200 tokens)
   - `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens)
   - `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties
   - `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation
   - Show workflow architecture to user for approval before proceeding

5. **Validation Phase** (parallel for multiple nodes)
   - `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check
   - `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
   - Fix ALL errors before proceeding

6. **Building Phase**
   - If using template: `get_template(templateId, {mode: "full"})`
   - **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
   - Build from validated configurations
   - ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
   - Connect nodes with proper structure
   - Add error handling
   - Use n8n expressions: $json, $node["NodeName"].json
   - Build in artifact (unless deploying to n8n instance)

7. **Workflow Validation** (before deployment)
   - `validate_workflow(workflow)` - Complete validation
   - `validate_workflow_connections(workflow)` - Structure check
   - `validate_workflow_expressions(workflow)` - Expression validation
   - Fix ALL issues before deployment

8. **Deployment** (if n8n API configured)
   - `n8n_create_workflow(workflow)` - Deploy
   - `n8n_validate_workflow({id})` - Post-deployment check
   - `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
   - `n8n_test_workflow({workflowId})` - Test workflow execution

## Critical Warnings

### ⚠️ Never Trust Defaults
Default values cause runtime failures. Example:
```json
// ❌ FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}

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

### ⚠️ Example Availability
`includeExamples: true` returns real configurations from workflow templates.
- Coverage varies by node popularity
- When no examples available, use `get_node` + `validate_node({mode: 'minimal'})`

## Validation Strategy

### Level 1 - Quick Check (before building)
`validate_node({nodeType, config, mode: 'minimal'})` - Required fields only ( *"Before MCP, I was translating. Now I'm composing. And that changes everything about how we can build automation."*

When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transformative:

**Without MCP:** "I was basically playing a guessing game. 'Is it `scheduleTrigger` or `schedule`? Does it take `interval` or `rule`?' I'd write what seemed logical, but n8n has its own conventions that you can't just intuit. I made six different configuration errors in a simple HackerNews scraper."

**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node()` and get exactly what I needed - not a 100KB JSON dump, but the actual properties that matter. What took 45 minutes now takes 3 minutes."

**The Real Value:** "It's about confidence. When you're building automation workflows, uncertainty is expensive. One wrong parameter and your workflow fails at 3 AM. With MCP, I could validate my configuration before deployment. That's not just time saved - that's peace of mind."

[Read the full interview →](docs/CLAUDE_INTERVIEW.md)

## 📡 Available MCP Tools

Once connected, Claude can use these powerful tools:

### Core Tools (7 tools)
- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
- **`search_nodes`** - Full-text search across all nodes. Use `source: 'community'|'verified'` for community nodes, `includeExamples: true` for configs
- **`get_node`** - Unified node information tool with multiple modes (v2.26.0):
  - **Info mode** (default): `detail: 'minimal'|'standard'|'full'`, `includeExamples: true`
  - **Docs mode**: `mode: 'docs'` - Human-readable markdown documentation
  - **Property search**: `mode: 'search_properties'`, `propertyQuery: 'auth'`
  - **Versions**: `mode: 'versions'|'compare'|'breaking'|'migrations'`
- **`validate_node`** - Unified node validation (v2.26.0):
  - `mode: 'minimal'` - Quick required fields check (