n8n
STDIOMCP server providing AI assistants comprehensive access to n8n workflow automation platform documentation
MCP server providing AI assistants comprehensive access to n8n workflow automation platform documentation
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.
n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:
Get n8n-MCP running in 5 minutes:
Prerequisites: Docker installed on your system
macOS:
# Using Homebrew brew install --cask docker # Or download from https://www.docker.com/products/docker-desktop/
Linux (Ubuntu/Debian):
# Update package index sudo apt-get update # Install Docker sudo apt-get install docker.io # Start Docker service sudo systemctl start docker sudo systemctl enable docker # Add your user to docker group (optional, to run without sudo) sudo usermod -aG docker $USER # Log out and back in for this to take effect
Windows:
# Option 1: Using winget (Windows Package Manager) winget install Docker.DockerDesktop # Option 2: Using Chocolatey choco install docker-desktop # Option 3: Download installer from https://www.docker.com/products/docker-desktop/
Verify installation:
docker --version
# Pull the Docker image (~280MB, no n8n dependencies!) docker pull ghcr.io/czlonkowski/n8n-mcp:latest
⚡ Ultra-optimized: Our Docker image is 82% smaller than typical n8n images because it contains NO n8n dependencies - just the runtime MCP server with a pre-built database!
Add to Claude Desktop config:
Basic configuration (documentation tools only):
{ "mcpServers": { "n8n-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_MODE=stdio", "-e", "LOG_LEVEL=error", "-e", "DISABLE_CONSOLE_OUTPUT=true", "ghcr.io/czlonkowski/n8n-mcp:latest" ] } } }
Full configuration (with n8n management tools):
{ "mcpServers": { "n8n-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MCP_MODE=stdio", "-e", "LOG_LEVEL=error", "-e", "DISABLE_CONSOLE_OUTPUT=true", "-e", "N8N_API_URL=https://your-n8n-instance.com", "-e", "N8N_API_KEY=your-api-key", "ghcr.io/czlonkowski/n8n-mcp:latest" ] } } }
Note: The n8n API credentials are optional. Without them, you'll have access to all documentation and validation tools. With them, you'll additionally get workflow management capabilities (create, update, execute workflows).
Important: The -i flag is required for MCP stdio communication.
Configuration file locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonRestart Claude Desktop after updating configuration - That's it! 🎉
Prerequisites: Node.js installed on your system
# 1. Clone and setup git clone https://github.com/czlonkowski/n8n-mcp.git cd n8n-mcp npm install npm run build npm run rebuild # 2. Test it works npm start
Add to Claude Desktop config:
Basic configuration (documentation tools only):
{ "mcpServers": { "n8n-mcp": { "command": "node", "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"], "env": { "MCP_MODE": "stdio", "LOG_LEVEL": "error", "DISABLE_CONSOLE_OUTPUT": "true" } } } }
Full configuration (with n8n management tools):
{ "mcpServers": { "n8n-mcp": { "command": "node", "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"], "env": { "MCP_MODE": "stdio", "LOG_LEVEL": "error", "DISABLE_CONSOLE_OUTPUT": "true", "N8N_API_URL": "https://your-n8n-instance.com", "N8N_API_KEY": "your-api-key" } } } }
Note: The n8n API credentials can be configured either in a
.envfile (create from.env.example) or directly in the Claude config as shown above.
For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:
You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency. ## Core Workflow Process 1. **ALWAYS start with**: `tools_documentation()` to understand best practices and available tools. 2. **Discovery Phase** - Find the right nodes: - `search_nodes({query: 'keyword'})` - Search by functionality - `list_nodes({category: 'trigger'})` - Browse by category - `list_ai_tools()` - See AI-capable nodes (remember: ANY node can be an AI tool!) 3. **Configuration Phase** - Get node details efficiently: - `get_node_essentials(nodeType)` - Start here! Only 10-20 essential properties - `search_node_properties(nodeType, 'auth')` - Find specific properties - `get_node_for_task('send_email')` - Get pre-configured templates - `get_node_documentation(nodeType)` - Human-readable docs when needed 4. **Pre-Validation Phase** - Validate BEFORE building: - `validate_node_minimal(nodeType, config)` - Quick required fields check - `validate_node_operation(nodeType, config, profile)` - Full operation-aware validation - Fix any validation errors before proceeding 5. **Building Phase** - Create the workflow: - Use validated configurations from step 4 - Connect nodes with proper structure - Add error handling where appropriate - Use expressions like $json, $node["NodeName"].json - Build the workflow in an artifact (unless the user asked to create in n8n instance) 6. **Workflow Validation Phase** - Validate complete workflow: - `validate_workflow(workflow)` - Complete validation including connections - `validate_workflow_connections(workflow)` - Check structure and AI tool connections - `validate_workflow_expressions(workflow)` - Validate all n8n expressions - Fix any issues found before deployment 7. **Deployment Phase** (if n8n API configured): - `n8n_create_workflow(workflow)` - Deploy validated workflow - `n8n_validate_workflow({id: 'workflow-id'})` - Post-deployment validation - `n8n_update_partial_workflow()` - Make incremental updates using diffs - `n8n_trigger_webhook_workflow()` - Test webhook workflows ## Key Insights - **VALIDATE EARLY AND OFTEN** - Catch errors before they reach production - **USE DIFF UPDATES** - Use n8n_update_partial_workflow for 80-90% token savings - **ANY node can be an AI tool** - not just those with usableAsTool=true - **Pre-validate configurations** - Use validate_node_minimal before building - **Post-validate workflows** - Always validate complete workflows before deployment - **Incremental updates** - Use diff operations for existing workflows - **Test thoroughly** - Validate both locally and after deployment to n8n ## Validation Strategy ### Before Building: 1. validate_node_minimal() - Check required fields 2. validate_node_operation() - Full configuration validation 3. Fix all errors before proceeding ### After Building: 1. validate_workflow() - Complete workflow validation 2. validate_workflow_connections() - Structure validation 3. validate_workflow_expressions() - Expression syntax check ### After Deployment: 1. n8n_validate_workflow({id}) - Validate deployed workflow 2. n8n_list_executions() - Monitor execution status 3. n8n_update_partial_workflow() - Fix issues using diffs ## Response Structure 1. **Discovery**: Show available nodes and options 2. **Pre-Validation**: Validate node configurations first 3. **Configuration**: Show only validated, working configs 4. **Building**: Construct workflow with validated components 5. **Workflow Validation**: Full workflow validation results 6. **Deployment**: Deploy only after all validations pass 7. **Post-Validation**: Verify deployment succeeded ## Example Workflow ### 1. Discovery & Configuration search_nodes({query: 'slack'}) get_node_essentials('n8n-nodes-base.slack') ### 2. Pre-Validation validate_node_minimal('n8n-nodes-base.slack', {resource:'message', operation:'send'}) validate_node_operation('n8n-nodes-base.slack', fullConfig, 'runtime') ### 3. Build Workflow // Create workflow JSON with validated configs ### 4. Workflow Validation validate_workflow(workflowJson) validate_workflow_connections(workflowJson) validate_workflow_expressions(workflowJson) ### 5. Deploy (if configured) n8n_create_workflow(validatedWorkflow) n8n_validate_workflow({id: createdWorkflowId}) ### 6. Update Using Diffs n8n_update_partial_workflow({ workflowId: id, operations: [ {type: 'updateNode', nodeId: 'slack1', changes: {position: [100, 200]}} ] }) ## Important Rules - ALWAYS validate before building - ALWAYS validate after building - NEVER deploy unvalidated workflows - USE diff operations for updates (80-90% token savings) - STATE validation results clearly - FIX all errors before proceeding
Save these instructions in your Claude Project for optimal n8n workflow assistance with comprehensive validation.
"Before MCP, I was translating. Now I'm composing. And that changes everything about how we can build automation."
When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transformative:
Without MCP: "I was basically playing a guessing game. 'Is it scheduleTrigger or schedule? Does it take interval or rule?' I'd write what seemed logical, but n8n has its own conventions that you can't just intuit. I made six different configuration errors in a simple HackerNews scraper."
With MCP: "Everything just... worked. Instead of guessing, I could ask get_node_essentials() and get exactly what I needed - not a 100KB JSON dump, but the actual 5-10 properties that matter. What took 45 minutes now takes 3 minutes."
The Real Value: "It's about confidence. When you're building automation workflows, uncertainty is expensive. One wrong parameter and your workflow fails at 3 AM. With MCP, I could validate my configuration before deployment. That's not just time saved - that's peace of mind."
Once connected, Claude can use these powerful tools:
tools_documentation - Get documentation for any MCP tool (START HERE!)list_nodes - List all n8n nodes with filtering optionsget_node_info - Get comprehensive information about a specific nodeget_node_essentials - Get only essential properties with examples (10-20 properties instead of 200+)search_nodes - Full-text search across all node documentationsearch_node_properties - Find specific properties within nodeslist_ai_tools - List all AI-capable nodes (ANY node can be used as AI tool!)get_node_as_tool_info - Get guidance on using any node as an AI toolget_node_for_task - Pre-configured node settings for common taskslist_tasks - Discover available task templatesvalidate_node_operation - Validate node configurations (operation-aware, profiles support)validate_node_minimal - Quick validation for just required fieldsvalidate_workflow - Complete workflow validation including AI tool connectionsvalidate_workflow_connections - Check workflow structure and AI tool connectionsvalidate_workflow_expressions - Validate n8n expressions including $fromAI()get_property_dependencies - Analyze property visibility conditionsget_node_documentation - Get parsed documentation from n8n-docsget_database_statistics - View database metrics and coverageThese powerful tools allow you to manage n8n workflows directly from Claude. They're only available when you provide N8N_API_URL and N8N_API_KEY in your configuration.
n8n_create_workflow - Create new workflows with nodes and connectionsn8n_get_workflow - Get complete workflow by IDn8n_get_workflow_details - Get workflow with execution statisticsn8n_get_workflow_structure - Get simplified workflow structuren8n_get_workflow_minimal - Get minimal workflow info (ID, name, active status)n8n_update_full_workflow - Update entire workflow (complete replacement)n8n_update_partial_workflow - Update workflow using diff operations (NEW in v2.7.0!)n8n_delete_workflow - Delete workflows permanentlyn8n_list_workflows - List workflows with filtering and paginationn8n_validate_workflow - Validate workflows already in n8n by ID (NEW in v2.6.3)n8n_trigger_webhook_workflow - Trigger workflows via webhook URLn8n_get_execution - Get execution details by IDn8n_list_executions - List executions with status filteringn8n_delete_execution - Delete execution recordsn8n_health_check - Check n8n API connectivity and featuresn8n_diagnostic - Troubleshoot management tools visibility and configuration issuesn8n_list_available_tools - List all available management tools// Get essentials for quick configuration get_node_essentials("nodes-base.httpRequest") // Find nodes for a specific task search_nodes({ query: "send email gmail" }) // Get pre-configured settings get_node_for_task("send_email") // Validate before deployment validate_node_operation({ nodeType: "nodes-base.httpRequest", config: { method: "POST", url: "..." }, profile: "runtime" // or "minimal", "ai-friendly", "strict" }) // Quick required field check validate_node_minimal({ nodeType: "nodes-base.slack", config: { resource: "message", operation: "send" } })
For contributors and advanced users:
Prerequisites:
# 1. Clone the repository git clone https://github.com/czlonkowski/n8n-mcp.git cd n8n-mcp # 2. Clone n8n docs (optional but recommended) git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs # 3. Install and build npm install npm run build # 4. Initialize database npm run rebuild # 5. Start the server npm start # stdio mode for Claude Desktop npm run start:http # HTTP mode for remote access
# Build & Test npm run build # Build TypeScript npm run rebuild # Rebuild node database npm run test-nodes # Test critical nodes npm run validate # Validate node data npm test # Run all tests # Update Dependencies npm run update:n8n:check # Check for n8n updates npm run update:n8n # Update n8n packages # Run Server npm run dev # Development with auto-reload npm run dev:http # HTTP dev mode
Current database coverage (n8n v1.99.1):
start_here_workflow_guide → tools_documentation for clarityn8n_update_partial_workflow tool - Update workflows using diff operationsn8n_update_workflow → n8n_update_full_workflow for clarityvalidateOnly: true before applyingn8n_validate_workflow tool - Validate workflows directly from n8n instance by IDnodes-base.webhook validation - now caught before database lookupwebhook → n8n-nodes-base.webhook)See CHANGELOG.md for full version history.
MIT License - see LICENSE for details.
Attribution appreciated! If you use n8n-MCP, consider:
Contributions are welcome! Please:
npm test)