io.github.leonardosepulvedat/mcp-n8n

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"

"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

• 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.

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

• n8n API Documentation
• Model Context Protocol
• n8n Community
• MCP Servers Registry

---

⚠️ 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

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

---