MCP n8n Server

Operate and build n8n from Cursor or Claude — administration of your instance (users, projects, executions, audit) and a full builder loop: a catalog of 560 nodes with real parameter schemas extracted from the official n8n packages, validation before saving, automatic repair, snapshots with rollback and diff, per-node execution debugging, health reports, and full-instance backup.

Two env vars. Runs on your machine (stdio) or as a remote HTTP server. No hosted account.

🎯 Token Optimization

This server is optimized to minimize token consumption, addressing one of the biggest issues with MCP servers - excessive API token usage.

What We've Optimized:

• 90% reduction in tokens for workflow listing with new n8n_list_workflows_summary endpoint
• Field filtering - request only the data you need
• Smart defaults - reduced from 100 to 10-20 results per query
• Intelligent warnings - alerts when operations will consume significant tokens

See TOKEN_OPTIMIZATION.md for detailed usage guide.

✨ Features

🔄 Workflow Management

• Create & Deploy: Build workflows with natural language descriptions
• CRUD Operations: Full lifecycle management (Create, Read, Update, Delete)
• Activation Control: Enable/disable workflows on demand
• Project Transfer: Move workflows between projects seamlessly
• Tag Management: Organize workflows with custom tags

📊 Execution Monitoring

• Real-time Tracking: Monitor workflow executions with advanced filters
• Detailed Insights: Access full execution data and logs
• Error Recovery: Retry failed executions automatically
• Cleanup Tools: Manage execution history efficiently

🔐 Credential Management

• Secure Creation: Add credentials for any service
• Schema Discovery: Auto-discover required fields for credential types
• Project Isolation: Transfer credentials between projects safely
• Type Support: Compatible with all n8n credential types

🧱 Workflow Builder

• Full node catalog — 560 nodes with real schemas: extracted directly from n8n-nodes-base and @n8n/n8n-nodes-langchain (parameters with types, allowed options, display conditions, credentials, latest typeVersion), regenerated weekly by CI. Search with n8n_search_nodes, inspect with n8n_get_node
• Real validation: n8n_validate_workflow checks against the real schemas — nonexistent node types, missing required params (including conditionally required ones), invalid option values, wrong typeVersion, broken connections — before save/activate
• Expression linting: detects {{ }} expressions missing the = prefix and references to nodes that don't exist in the workflow
• Automatic repair: n8n_autofix_workflow fixes missing typeVersion/positions, duplicate names, dangling connections and expression prefixes — preview first, apply with a snapshot
• Surgical edits: n8n_update_workflow_partial adds/removes nodes and connections without rewriting the whole flow
• Public templates: search and import from n8n.io (n8n_search_public_templates, n8n_import_public_template) plus 100 bundled templates as a fallback
• Guided prompts: MCP prompts build-workflow and fix-workflow walk any agent through the full build/validate/test/repair loop

🔬 Deep Debugging & Health

• Per-node execution data: n8n_get_node_execution_data shows exactly what data flowed through one node (status, item counts, output samples, error details) without downloading the whole execution
• Debug loop: n8n_debug_last_error returns the failing node and message from the last error
• Health reports: n8n_workflow_health computes success rate, failure count, average duration and last failure per workflow from recent executions, sorted worst-first

🛡️ Safety Net & Real Testing

• Automatic snapshots: before every update, partial edit, autofix, or delete, the previous state is saved locally (~/.mcp-n8n/snapshots, configurable with N8N_SNAPSHOT_DIR)
• Rollback: n8n_rollback_workflow restores any snapshot — even recreates a deleted workflow (recreate=true)
• Diff: n8n_diff_workflow_snapshot compares a snapshot against the current state (nodes added/removed/modified, changed parameters, connection changes) before deciding to roll back
• Full-instance backup: n8n_export_all_workflows saves every workflow as JSON files; n8n_import_workflows restores them
• End-to-end testing: n8n_trigger_webhook calls a Webhook-trigger workflow on the instance and returns the real HTTP response, so the agent can verify the flow actually works

🎯 Bundled Templates

• 100 local starting points with keyword matching, if you prefer not to hit n8n.io

🏗️ Organization & Administration

• Tags: Categorize and organize resources
• Variables: Centralized environment variable management
• Projects: Multi-tenant project support
• Users & Permissions: Complete access control management
• Audit Logs: Generate security and compliance reports

🚀 Quick Start

Installation via npm (Recommended)

This is the easiest way to get started:

npm install -g mcp-n8n

Configuration

1. Get your n8n API credentials:

   • Navigate to your n8n instance → Settings → n8n API
   • Generate a new API key

2. Configure Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Option A - Using global installation (if you ran npm install -g mcp-n8n):

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS is optional (all by default). Use core,builder if you want operations + creation without user/project admin tools. Use admin only for instance administration.

Remote HTTP mode (optional)

By default the server communicates over stdio (local). To run it as a shared remote server (e.g. in Docker or on a VPS), set a port:

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

This exposes the MCP protocol over streamable HTTP on port 3000 plus a GET /health endpoint. N8N_MCP_HTTP_TOKEN is strongly recommended: when set, every request must include Authorization: Bearer <token>. Point any MCP client that supports streamable HTTP at http://your-host:3000 with that header.

Option B - Using npx (no installation needed, always latest version):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Configure Cursor:

Add to Cursor MCP settings (Settings → Extensions → MCP):

Recommended - Using npx (always uses latest version):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: Cursor requires using npx for MCP servers. The -y flag automatically installs/updates the package without prompting.

Option C - Docker:

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

The /data volume persists workflow snapshots between runs.

4. Restart Claude Desktop or Cursor

💬 Usage Examples

Once configured, interact with n8n using natural language:

Creating Workflows

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

Using Templates

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

Managing Workflows

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

Monitoring & Debugging

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"