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:

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