n8n MCP Server

## MCP-Based n8n Workflow Builder A comprehensive MCP (Model Context Protocol) server for building, managing, and executing **any n8n workflow** via the n8n REST API. This tool removes all node type restrictions and provides full access to your n8n instance's capabilities. ### Key Features 🚀 **Universal Node Support** - Create workflows with ANY n8n node type (no restrictions!) 🔌 **Comprehensive API Coverage** - Workflows, credentials, executions, and node type management 🌲 **Complex Workflows** - Full support for branching (IF/Switch), error workflows, and multi-path flows 📊 **Execution Monitoring** - Track workflow runs, view results, and manage execution history 🔐 **Credential Management** - Securely manage n8n credentials programmatically 🎯 **Smart Validation** - Dynamic validation against your n8n instance's available nodes 📝 **Audit Logging** - Complete audit trail of all operations ⚡ **Rate Limiting** - Built-in protection for your n8n instance 🏎️ **High Performance** - Connection pooling, retry logic, and bulk operations ✨ NEW 🔗 **Webhook URLs** - Automatically retrieve webhook endpoints ✨ NEW 🛡️ **Circuit Breaker** - Automatic failure detection and recovery ✨ NEW 💾 **Node Type Caching** - 1-hour cache for faster node type lookups ✨ NEW 📊 **Metrics & Monitoring** - Real-time metrics, health checks, and observability ✨ NEW ### MCP Tools Available (28 Total) **Workflow Management:** - `validate_workflow` - Validate workflow specs offline - `list_workflows` - List with filtering (name, active status) - `create_workflow` - Create with dry-run, auto-activate, overwrite - `get_workflow` - Fetch full workflow JSON - `update_workflow` - Partial updates by ID or name - `delete_workflow` - Remove workflows - `activate_workflow` - Enable/disable workflows - `duplicate_workflow` - Clone with custom suffix - `execute_workflow` - Trigger with custom payload - `get_webhook_urls` - Get webhook URLs for a workflow ✨ NEW - `bulk_activate_workflows` - Activate/deactivate multiple workflows in parallel ✨ NEW - `bulk_delete_workflows` - Delete multiple workflows in parallel ✨ NEW **Execution Monitoring:** - `list_executions` - View execution history (filter by workflow) - `get_execution` - Get detailed execution data & results - `delete_execution` - Clean up execution history **Credential Management:** - `list_credentials` - List all credentials (filter by type) - `get_credential` - View credential details (sensitive data redacted) - `create_credential` - Add new credentials - `update_credential` - Modify existing credentials - `delete_credential` - Remove credentials **Node Discovery:** - `list_node_types` - Get all available node types in your instance - `get_node_type` - Get detailed node documentation and parameters **System Monitoring:** - `get_circuit_breaker_stats` - Monitor API health and circuit breaker state ✨ NEW - `reset_circuit_breaker` - Manually reset circuit breaker after n8n recovery ✨ NEW - `get_metrics` - Comprehensive metrics (requests, latency, errors, cache) ✨ NEW - `get_health_status` - Overall health checks with detailed status ✨ NEW - `reset_metrics` - Reset all collected metrics ✨ NEW ### Quickstart 1. **Configure your n8n connection:** ```bash cp .env.template .env # Edit .env with your n8n URL and API key ``` 2. **Install dependencies:** ```bash python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt ``` 3. **Run MCP server:** ```bash python -m mcp_server # Runs health check then starts server ``` 4. **Use with any MCP client** (Claude Desktop, etc.) ### Example: Create a Complex Workflow ```json { "name": "Advanced Email Processor", "nodes": [ { "name": "Email Trigger", "type": "n8n-nodes-base.emailReadImap", "parameters": { "mailbox": "INBOX", "options": {} } }, { "name": "Check Priority", "type": "n8n-nodes-base.if", "parameters": { "conditions": { "string": [ { "value1": "={{$json.subject}}", "operation": "contains", "value2": "URGENT" } ] } } }, { "name": "Slack Alert", "type": "n8n-nodes-base.slack", "parameters": { "resource": "message", "operation": "post", "channel": "#urgent", "text": "Urgent email: {{$json.subject}}" } }, { "name": "Save to Database", "type": "n8n-nodes-base.postgres", "parameters": { "operation": "insert", "table": "emails" } } ], "connections": [ {"fromNode": "Email Trigger", "toNode": "Check Priority"}, {"fromNode": "Check Priority", "toNode": "Slack Alert", "branch": 0}, {"fromNode": "Check Priority", "toNode": "Save to Database", "branch": 1} ] } ``` ### Project Structure - `core/` - Workflow builder, validator, config, logging, cache, circuit breaker, metrics, workflow helpers - `client/` - n8n REST API client with full endpoint coverage - `mcp_server/` - MCP server with 28 tools - `ui/` - Optional Gradio web interface - `templates/` - Example workflow templates - `examples/` - Usage examples and patterns - `tests/` - Comprehensive test suite (65+ tests, 100% passing) ### Testing Run the test suite: ```bash pytest tests/ -v ``` Test coverage includes: - ✅ **Core modules**: Workflow builder, validator, utilities - ✅ **Security**: Sensitive data redaction in audit logs - ✅ **Reliability**: Circuit breaker pattern, rate limiting - ✅ **Performance**: Caching with TTL support - ✅ **MCP tools**: Tool registration and execution - **65+ tests total** with comprehensive edge case coverage ### Workflow Builder API Programmatically build workflows with a fluent, chainable API: ```python from core.workflow_helpers import WorkflowBuilder # Build a workflow fluently workflow = ( WorkflowBuilder("GitHub Alert System") .add_webhook("Trigger", "/github", "POST") .add_http_request("Fetch Data", "https://api.github.com/repos/={{$json.repo}}") .add_if_condition("Check Stars", "={{$json.stargazers_count}}", "greaterThan", 100) .add_slack("Trending Alert", "#trending", "🔥 Repo is trending!") .add_slack("Normal Log", "#activity", "New activity logged") .connect("Trigger", "Fetch Data") .connect("Fetch Data", "Check Stars") .connect("Check Stars", "Trending Alert", branch=0) # True .connect("Check Stars", "Normal Log", branch=1) # False .build() ) ``` **Supported Node Types:** - `add_webhook()` - Webhook triggers - `add_http_request()` - HTTP API calls - `add_slack()` - Slack notifications - `add_email()` - Email sending - `add_if_condition()` - Conditional branching - `add_function()` - Custom JavaScript - `add_set()` - Data transformation - `add_node()` - Any n8n node type **Helper Functions:** - `create_simple_webhook_workflow()` - Quick webhook → action workflows - `create_conditional_workflow()` - If/then/else patterns See `examples/workflow_builder_example.py` for complete examples. ### Advanced Features **Complex Branching:** ```json { "fromNode": "Switch", "toNode": "Path1", "branch": 0 }, { "fromNode": "Switch", "toNode": "Path2", "branch": 1 } ``` **Error Workflows:** ```json { "fromNode": "HTTP Request", "toNode": "Error Handler", "output": "error" } ``` **Dynamic Node Discovery:** Query your instance for available nodes and get detailed documentation: - Use `list_node_types()` to see all available nodes - Use `get_node_type("n8n-nodes-base.gmail")` for specific node details ### Security - ✅ All secrets via environment variables (never hardcoded) - ✅ Automatic redaction of sensitive data in audit logs (passwords, API keys, tokens, etc.) - ✅ Comprehensive test suite for security features - ✅ Rate limiting (default: 60 requests/minute) - ✅ API key authentication with n8n - ✅ Audit trail for all destructive operations - ✅ Security best practices documented in .env.template - ✅ Recursive sanitization prevents credential leaks in nested objects ### Requirements - Python 3.9+ - n8n instance with API access enabled - n8n API key (generated in n8n Settings → API) ### Configuration See `.env.template` for all options: - `N8N_API_URL` - Your n8n instance URL - `N8N_API_KEY` - Your n8n API key - `N8N_VERSION` - Target n8n version (optional) - `RATE_LIMIT` - Requests per minute (default: 60) - `LOG_LEVEL` - Logging verbosity (default: info) ### What's New This version removes ALL node type restrictions and adds: - Support for **any n8n node type** (Gmail, Sheets, Airtable, custom nodes, etc.) - Full credential management (list, create, update, delete) - Execution monitoring and history - Node type discovery and documentation - Complex workflow branching (IF/Switch with multiple outputs) - Error workflow support - Dynamic validation against your n8n instance ### Documentation For detailed usage examples and API documentation, see the inline docstrings and `/templates` directory for canonical workflow examples.