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

Get your n8n API credentials:
- Navigate to your n8n instance → Settings → n8n API
- Generate a new API key
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"
      }
    }
  }
}

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.

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"

"Delete all successful executions older than 30 days"

🛠️ Available Tools

Workflows

n8n_create_workflow - Create new workflows (validate first)
n8n_list_workflows_summary - Token-efficient listing
n8n_list_workflows - Full details with optional field filtering
n8n_get_workflow - Full workflow JSON
n8n_update_workflow - Replace fields (omitted fields keep current values)
n8n_update_workflow_partial - Surgical edits: add/remove nodes and connections
n8n_delete_workflow - Remove workflows permanently
n8n_activate_workflow / n8n_deactivate_workflow
n8n_transfer_workflow / tags tools

Safety & Testing

n8n_list_workflow_snapshots - Local history of every change made through this server
n8n_rollback_workflow - Restore a previous version, or recreate a deleted workflow
n8n_diff_workflow_snapshot - Compare a snapshot against the current state before rolling back
n8n_trigger_webhook - Call a webhook workflow and get the real response
n8n_export_all_workflows / n8n_import_workflows - Full-instance backup and restore

Builder

n8n_search_nodes / n8n_get_node - Full catalog: 560 nodes with real parameter schemas
n8n_validate_workflow - Check JSON against real schemas before save/activate
n8n_autofix_workflow - Mechanical repairs: typeVersion, positions, duplicates, dangling connections, expression prefixes
n8n_search_public_templates / n8n_import_public_template - Official n8n.io library
n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template - Bundled templates

100 Included Templates across 13 categories:

E-commerce: Shopify automation, WooCommerce support agents
Social Media: Instagram, TikTok, LinkedIn, Twitter automation
AI/Chat: Chatbots, AI agents, voice assistants
Communication: WhatsApp, Telegram, Email automation
Content: Blog automation, video generation, SEO optimization
HR/Recruitment: Resume screening, candidate sourcing
Sales/CRM: Lead generation, cold calling pipelines
Finance: Stock analysis, invoice extraction
Data Scraping: Google Maps, LinkedIn, Amazon, TikTok
Monitoring: Website uptime, competitor tracking
Productivity: Calendar, Notion, scheduling automation

Executions (4 tools)

n8n_list_executions - Filter by status, workflow, project
n8n_get_execution - Detailed execution data
n8n_delete_execution - Remove execution records
n8n_retry_execution - Retry failed executions
n8n_debug_last_error - Failing node + message from the last error
n8n_get_node_execution_data - Data that flowed through one specific node
n8n_workflow_health - Success rate, failures and duration per workflow

Credentials (4 tools)

n8n_create_credential - Add new credentials
n8n_delete_credential - Remove credentials (owner only)
n8n_get_credential_schema - Discover required fields
n8n_transfer_credential - Move between projects

Organization (19 tools)

Tags: Create, list, get, update, deleteVariables: Create, list, update, deleteUsers: List, create, get, delete, change roleProjects: Create, list, update, delete, manage users

Advanced (2 tools)

n8n_generate_audit - Security audit reports
n8n_pull_source_control - Version control integration

61 tools by default (N8N_TOOLSETS=all). core,builder exposes 28. Plus 2 MCP prompts (build-workflow, fix-workflow).

📚 Documentation

Quick Start Guide - Get up and running in 5 minutes
Examples & Use Cases - Real-world automation examples
Node Reference - Detailed tool documentation
Changelog - Version history and updates

🏗️ Project Structure

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

🔧 Development

Local Installation (For Development)

If you want to contribute or test local changes:

1. Setup

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. Configure with Local Build

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

For Cursor, add to MCP settings:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important: Replace /absolute/path/to/mcp-n8n/ with the actual absolute path to your cloned repository (e.g., /Users/yourname/projects/mcp-n8n/).

3. Testing

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

How to Run

To run the main script, execute:

python main.py

How to Test

To run the tests, execute:

pytest test_main.py

📋 Requirements

Node.js: 20 or higher
n8n Instance: Self-hosted or n8n Cloud (paid plan)
n8n API Key: Required for authentication
AI IDE: Claude Desktop or Cursor with MCP support

n8n Requirements

Self-hosted: Full API access ✅
n8n Cloud: Requires paid plan for API access
Version: Compatible with n8n v1.0.0+

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

n8n - The workflow automation platform
Anthropic - Claude and Model Context Protocol
Cursor - AI-powered code editor

🔗 Resources

⚠️ Important Notes

API Access

n8n Cloud requires a paid plan to access the API
Self-hosted n8n has full API access on all plans
Some operations require owner/admin permissions

Security

Never commit .env files with credentials
Use environment variables for sensitive data
API keys grant full access to your n8n instance
Regularly rotate API keys for security

Rate Limiting

Respect n8n API rate limits
Use pagination for large result sets
Implement error handling for rate limit responses

🐛 Troubleshooting

Connection Issues

Problem: "Cannot connect to n8n API"

Verify N8N_BASE_URL is correct and accessible
Check that API key is valid
Ensure n8n instance is running

Permission Errors

Problem: "Insufficient permissions"

Some operations require owner/admin role
Verify your user has appropriate permissions
Check project-level access rights

Template Issues

Problem: "Template not found"

Ensure examples/ directory is present
Verify templates-metadata.json exists
Check template file references are correct

💡 Tips & Best Practices

Start with Templates: Use pre-built templates as starting points
Use Tags: Organize workflows with tags for easy management
Monitor Executions: Regularly check failed executions
Clean Up: Remove old execution data to save space
Version Control: Use n8n's built-in version control features
Test First: Test workflows before activating in production

📧 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
n8n Community: community.n8n.io

⬆ Back to Top