mcp-n8n

Operate and build n8n: 55 tools with validation, surgical edits, webhook testing and rollback.

GitHub
21
Try this MCPSponsored

Documentation

MCP n8n Server

npm version npm downloads CI License: MIT TypeScript n8n

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"
      }
    }
  }
}
  1. 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.

  1. 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, delete Variables: Create, list, update, delete Users: List, create, get, delete, change role Projects: 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

🏗️ 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.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. 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

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

📧 Support