🚀 n8n Workflow Builder MCP Server
An awesome MCP server for n8n that helps you build, optimize, and debug workflows - directly from Claude! 🎯
🌟 Features
🧠 AI-Powered Workflow Design
- Smart Node Suggestions: Simply describe what you want to build, and the server suggests the perfect nodes
- Template Generator: Generates complete workflow structures from natural language
- Best Practices: Knows n8n best practices and warns you about common mistakes
🔍 Workflow Analysis & Debugging
- Workflow Analyzer: Scans your workflows for issues and optimization potential
- Error Debugger: Helps you understand and fix workflow errors
- Security Checker: Finds hardcoded credentials and other security problems
📊 Workflow Management (Full CRUD)
- List & Filter: Overview of all workflows with status and info
- Details View: Detailed information about each workflow
- Execution Tracking: View past executions with status and errors
- Workflow Creation: Create new workflows from scratch or templates
- Workflow Editing: Smart merge updates - change names, modify nodes, adjust settings
- ✨ NEW: Intelligent node merging prevents accidental data loss (v1.13.2)
- ⚠️ Note:
activeandtagsfields are read-only and can only be changed in the n8n UI
- Workflow Deletion: Delete/archive workflows safely (v1.14.0)
⚡ Workflow Execution & Monitoring
- Manual Trigger: Start workflows directly from Claude (only for workflows with Manual/Webhook triggers)
- Custom Input Data: Pass dynamic data to your workflows
- Execution Details: Retrieve complete node input/output data for each execution
- Execution History: List of all past executions with status
🔄 Session State & Context Management
- Active Workflow Tracking: Automatically tracks which workflow you're currently working on
- Session History: Logs all your actions (analyze, execute, update, etc.)
- Recent Workflows: Quick access to your last 10 workflows
- Persistent State: Context survives between Claude conversations
- Smart Context: Reference workflows by "current" or "last workflow" instead of IDs
✅ Workflow Validation & Quality Assurance
- Pre-Deployment Validation: Comprehensive checks before deploying workflows
- Schema Validation: Ensures workflow structure is correct (required fields, types, etc.)
- Semantic Validation: Checks logical rules (trigger nodes, connections, duplicates)
- Parameter Validation: Node-specific parameter checks (webhooks, HTTP, databases, etc.)
- Security Checks: Detects hardcoded credentials, missing authentication
- Best Practices: Warns about default names, missing error handling, complexity
🤖 AI Feedback & Error Analysis
- Intelligent Error Analysis: Analyzes failed executions and identifies root causes
- Pattern Recognition: Detects common failure types (auth, network, data, SQL, rate limiting)
- AI-Friendly Feedback: Structured guidance for AI agents generating workflows
- Fix Examples: Wrong vs. Correct code comparisons
- Improvement Suggestions: Node-specific recommendations for fixing failures
- Learning Loop: AI agents learn from errors and generate better workflows
📚 Knowledge Base
- Node Encyclopedia: Detailed explanations of all important n8n nodes
- Use Cases & Examples: Practical examples for each node type
- Configuration Tips: How to optimally configure each node
🔐 Security Audits & Governance (NEW!)
- Hardcoded Secret Detection: Finds API keys, passwords, tokens, AWS keys, private keys, JWTs, database credentials
- 11 Secret Types: Detects AWS keys, GitHub tokens, OpenAI keys, Slack tokens, database URLs, and more
- Entropy Analysis: Uses Shannon entropy to detect high-entropy secrets (encrypted/encoded data)
- Authentication Auditing: Checks for missing/weak authentication, insecure HTTP, Basic Auth over HTTP
- Exposure Analysis: Identifies public webhooks, data leaks, PII exposure, CORS misconfigurations
- Security Scoring: 0-100 score with risk levels (Critical, High, Medium, Low, Excellent)
- Compliance Validation: Check workflows against Basic, Strict, or Enterprise standards
- Detailed Reports: Markdown/JSON/Text reports with findings, recommendations, and remediation steps
- Priority Findings: Get only critical/high severity issues for quick triage
🔬 Semantic Workflow Analysis
- Deep Logic Analysis: Goes beyond schema validation to understand workflow semantics
- 12 Anti-Pattern Checks: HTTP retry, loop completion, timezone config, IF paths, webhook security, infinite loops, credentials, N+1 queries, rate limiting, data validation, and more
- LLM-Friendly Fixes: Copy-paste ready code fixes for AI agents
- Severity Levels: Critical, High, Medium, Low prioritization
- Detailed Explanations: Why each issue matters and how it impacts workflows
- Security Scanning: Detects hardcoded credentials with regex patterns
- Performance Analysis: Identifies bottlenecks like N+1 queries
- Formatted Reports: Structured output optimized for AI consumption
🎯 Template Library & AI Recommendations
- 10+ Pre-Built Templates: Ready-to-use workflow templates for common use cases
- AI-Powered Recommendations: Get intelligent template suggestions based on your description
- Smart Relevance Scoring: Advanced algorithm matches templates to your requirements (70-90% accuracy)
- Category Browse: Templates organized by category (API, Reporting, Integration, etc.)
- Difficulty Levels: Beginner, Intermediate, and Advanced templates
- Full-Text Search: Search across names, descriptions, tags, and use cases
- Template Details: Complete implementation guides with estimated time and node structure
💭 Intent Metadata & AI Context (NEW!)
- "Why" Documentation: Attach reasoning, assumptions, and risks to each node
- AI Context Continuity: LLMs remember why nodes exist across iterations
- 5 Intent Fields: reason, assumption, risk, alternative, dependency
- Coverage Analysis: Track which nodes have intent metadata
- AI-Generated Suggestions: Get intent templates for undocumented nodes
- Workflow Understanding: Understand existing workflows faster
- Learning Loop: AI agents learn from past decisions
🔄 Execution-Aware Feedback Loop (NEW!)
- Real-Time Monitoring: Watch workflow executions and get instant error feedback
- Error Simplification: Complex n8n errors simplified for AI agents
- Context Extraction: Get full error context (node, input, output, error details)
- Pattern Analysis: Analyze error patterns across multiple executions
- Success Rate Tracking: Monitor workflow reliability over time
- Fix Suggestions: Specific recommendations for fixing failed nodes
- LLM-Optimized Output: Structured feedback designed for AI consumption
📊 Drift Detection & Degradation Analysis (NEW!)
Proactive quality monitoring that detects workflow degradation before it becomes critical
General Drift Detection
- Success Rate Drift: Detects >15% drop in workflow success rate
- Performance Drift: Identifies >50% increase in execution time
- New Error Patterns: Finds new error types that didn't exist before
- Error Frequency Drift: Detects 2x+ increase in existing error rates
- Change Point Detection: Pinpoints exactly when drift started
- Gradual vs Sudden Analysis: Classifies changes as gradual degradation or sudden breaks
Specialized Analyzers
- Schema Drift: API response structure changes (missing fields, type changes, null rate increases)
- Rate Limit Drift: 429 errors, throughput degradation, quota proximity warnings
- Data Quality Drift: Empty values, format violations, completeness degradation
Intelligent Analysis
- Root Cause Detection: 10+ evidence-based root causes (API rate limits, auth changes, schema changes, etc.)
- Confidence Scoring: 0.0-1.0 confidence for all analysis results
- Statistical Comparison: Baseline (first 30%) vs Current (last 30%) period analysis
- Evidence Collection: Tracks concrete metrics supporting each finding
Actionable Fixes
- Node-Specific Suggestions: Concrete fixes for each affected node
- Severity Grouping: Critical, Warning, and Info fixes
- Copy-Paste Ready: Implementation-ready code suggestions
- Testing Recommendations: Step-by-step testing guides
- Confidence Scores: Prioritize fixes by confidence level (85-95%)
Real-World Use Cases
✅ API Provider Changes: Detects when APIs change authentication, schemas, or rate limits ✅ Performance Degradation: Finds external service slowdowns before SLAs breach ✅ Credential Expiry: Identifies auth failures from expired tokens ✅ Data Quality Issues: Tracks increasing null values or format violations ✅ Rate Limit Problems: Catches approaching quota limits early
Requires: 20+ executions for reliable drift detection
📖 Explainability Layer (NEW!)
- Comprehensive Documentation: Automatic, audit-ready workflow documentation
- Purpose Analysis: Explains WHY workflows exist with business domain classification (10 domains)
- Data Flow Tracing: Complete data lineage from sources → transformations → destinations
- Dependency Mapping: Maps internal workflows + 25+ external services (Slack, Stripe, AWS, etc.)
- Risk Assessment: 5 risk categories (data loss, security, performance, availability, compliance)
- Mitigation Plans: Prioritized, actionable recommendations with confidence scores
- Multi-Format Export: Markdown (docs), JSON (APIs), Plain Text (console)
- AI-Native: Designed for LLM consumption with structured, consistent output
- Zero Configuration: Works instantly with any n8n workflow
🔮 Change Simulation & Approval System (NEW!)
- Terraform-Style Preview: Like
terraform planfor n8n workflows - see changes before applying - Breaking Change Detection: Automatically identifies critical changes (trigger removal, connection changes)
- Multi-Dimensional Impact Analysis: Analyzes impact across 5 dimensions (data flow, execution, dependencies, triggers, downstream)
- Risk Scoring: 0-10 risk score with severity levels (low, medium, high, critical)
- Dry-Run Validation: Validates structure, semantics, and performance without applying changes
- Approval Workflow: Create, review, approve/reject change requests with full audit trail
- Change History: Complete history of all workflow changes with timestamps and reviewers
- Color-Coded Output: 🔴 Breaking, 🟡 Structural, 🟢 Safe changes
- Performance Estimation: Predicts execution time, memory usage, complexity
- Recommendations: Actionable suggestions based on impact analysis
🎯 Intelligent Template System v2.0 (NEW!)
- Intent-Based Matching: Describe your goal → get smart template suggestions (not keyword search!)
- Multi-Source Adapters: Official n8n templates, GitHub repos, private repos
- Intent Extraction: Automatically extracts purpose, assumptions, risks, data flow from templates
- Trigger-Aware Scoring: Penalizes wrong trigger types (webhook when you need schedule)
- Template Adaptation: Modernizes 2022 templates → 2025-ready (placeholders, credentials, error handling)
- Provenance Tracking: Trust scores, success rates, usage stats for template reliability
- Semantic Understanding: "AI analysis" matches "machine learning", "telegram" matches "notification"
- Transparent Matching: Shows WHY templates match with detailed explanations
📦 Node Discovery System (NEW!)
Workflow-based learning that discovers available n8n nodes without API dependency
Intelligent Discovery
- Automatic Learning: Analyzes your workflows to discover all node types you use
- Real-World Schemas: Extracts actual parameters from live workflows (not documentation!)
- Usage Insights: Tracks node popularity, parameter types, credential requirements
- SQLite Persistence: Knowledge saved to
~/.n8n-mcp/node_discovery.db - Zero Configuration: Works on all n8n versions - no API required!
Smart Recommendations
- Task-Based Suggestions: "send slack message" → Telegram, Gmail, chatTrigger
- Advanced Scoring: Exact keyword (5pts), Synonym (2.5pts), Parameter (+1pt), Popularity (+3pts max)
- Bidirectional Synonyms: 40+ mappings (slack↔telegram, excel↔sheets, database↔postgres)
- Reason Generation: "Matches: send, message" or "Similar: slack" explains why nodes match
- Category Classification: ⚡trigger, 📊data_source, 🔄transform, 📬notification, 🌐http, 🔀logic, 🔧utility
Smart Search & Schema
- Keyword Search: Find nodes by name with category icons
- Detailed Schemas: Get parameter names, types, credentials, usage counts
- Parameter Type Inference: Learns types from real data (string, number, boolean, object, array)
- Usage Statistics: See which nodes are most popular in your workflows
Performance
- Fast Discovery: 100 workflows in ~15s
- Quick Recommendations: < 200ms for 100 discovered nodes
- In-Memory Caching: Database loaded on startup for instant queries
4 New Tools: discover_nodes, get_node_schema, search_nodes, recommend_nodes_for_task
🔄 Migration Engine
- Automatic Compatibility Checking: Detects deprecated nodes and parameters in workflows
- Smart Migration Rules: 7 built-in rules for common n8n nodes (HTTP, Postgres, Slack, etc.)
- Version Detection: Identifies compatibility issues from n8n 0.180.0 to 2.2.6
- n8n 2.0+ Support: Detects removed Start node, disabled ExecuteCommand/LocalFileTrigger, Code node security changes
- Dry-Run Mode: Preview changes before applying migrations
- Batch Operations: Check multiple workflows at once with summary statistics
- Severity Levels: Prioritize fixes by impact (critical, high, medium, low)
- Safe Transformations: Validates migrations to prevent data loss
- Detailed Reports: Complete before/after comparison and migration logs
🎯 Use Cases
1. From Workflow Idea to Finished Structure
You: "I need a workflow that fetches data from our Postgres DB daily at 9am,
calculates metrics, and sends a report via Slack"
Claude + MCP: Generates complete workflow structure with:
- Schedule Trigger (daily at 9am)
- Postgres Node (with query example)
- Function Node (metric calculation)
- Set Node (report formatting)
- Slack Node (with best practices)
2. Workflow Debugging
You: "My workflow throws 'timeout exceeded' errors"
Claude + MCP: Analyzes and suggests:
- Increase timeout settings
- Add retry logic
- Process data in batches
- Check external service performance
3. Workflow Optimization
You: "Analyze my workflow 'Daily Report Generator'"
Claude + MCP: Finds:
- 3 hardcoded API Keys (Security Issue!)
- Workflow could be split into 2 sub-workflows
- Missing error handling
- Node "HTTP Request" should be renamed
4. Smart Template Recommendations (NEW!)
You: "I need to send notifications to multiple channels when events occur"
Claude + MCP: Recommends:
1. Multi-Channel Notification System (85% match) - Beginner
- Perfect for system alerts and status updates
- Sends to Slack, Telegram, and Email simultaneously
- Estimated time: 20 minutes
2. Global Error Handler (62% match) - Intermediate
- Catches workflow errors and alerts team
- Includes logging and notification features
- Estimated time: 25 minutes
Use template 'notification_system' to get started!
5. Drift Detection (NEW!)
You: "My workflow was working fine last month, but now it keeps failing. What happened?"
Claude + MCP: Analyzes execution history with detect_workflow_drift:
📊 Drift Detected - Severity: CRITICAL
Metrics Comparison:
- Success Rate: 95% → 62% (-33%)
- Avg Duration: 1200ms → 1850ms (+54%)
Detected Patterns:
🔴 New Error Pattern: "429 Rate Limit Exceeded" (appeared 2 weeks ago)
⚠️ Performance Drift: Response times doubled gradually over 10 days
Next: Use get_drift_root_cause for detailed analysis
You: "What caused this drift?"
Claude + MCP: Uses get_drift_root_cause:
Root Cause: api_rate_limit_introduced
Confidence: 85%
Evidence:
- Rate limit errors appeared where none existed before
- Error started exactly 14 days ago
- Only affects HTTP Request nodes calling external API
Recommended Action:
Add request throttling or implement exponential backoff
You: "How do I fix it?"
Claude + MCP: Uses get_drift_fix_suggestions:
🔧 Suggested Fixes:
1. Add delay between requests (Node: Fetch User Data)
- Add 'Wait' node with 1-2 second delay
- Confidence: 85%
2. Implement retry logic with exponential backoff
- Use 'HTTP Request' retry settings: 3 attempts, exponential delay
- Confidence: 90%
Testing Recommendations:
✅ Test with rate-limited API first
✅ Monitor execution duration after changes
✅ Verify error rate drops below 5%
6. Migration Engine (NEW!)
You: "Check my workflow for compatibility issues"
Claude + MCP: Uses check_workflow_compatibility
✅ Compatibility Check Complete
Status: DEPRECATED (contains deprecated features)
Issues Found:
1. [HIGH] HTTP Request node (v2) - Parameter 'url' deprecated, use 'requestUrl'
2. [HIGH] HTTP Request node (v2) - Parameter 'method' deprecated, use 'requestMethod'
3. [MEDIUM] Slack node (v1) - Message formatting structure changed in v2
4. [LOW] Set node (v1) - New options structure in v2
Recommendation: Run migration to update nodes to latest versions
You: "Show me what would change if I migrate this workflow"
Claude + MCP: Uses get_migration_preview
Migration Preview:
Node: Send API Request (HTTP Request v2 → v3)
Changes:
- parameters.url → parameters.requestUrl
- parameters.method → parameters.requestMethod
- authentication moved to credentials field
Node: Notify Team (Slack v1 → v2)
Changes:
- parameters.message.text → parameters.text
- parameters.message.attachments → parameters.blocks
- markdown enabled by default
Total Changes: 2 nodes, 6 parameters
Risk Level: MEDIUM
You: "Migrate the workflow with dry-run first"
Claude + MCP: Uses migrate_workflow (dry_run=true)
Dry-Run Migration Complete ✅
Changes Applied (preview only):
✓ HTTP Request v2 → v3 (Send API Request)
✓ Slack v1 → v2 (Notify Team)
✓ Set v1 → v2 (Format Data)
Validation: PASSED
All connections preserved
No data loss detected
Ready to apply? Run without dry_run=true
You: "Apply the migration"
Claude + MCP: Uses migrate_workflow
Migration Applied Successfully! ✅
Updated Nodes:
✓ Send API Request (HTTP Request v3)
✓ Notify Team (Slack v2)
✓ Format Data (Set v2)
Workflow updated and saved
Test execution recommended
7. Workflow Explainability (NEW!)
You: "I need to document the 'Payment Processing' workflow for our SOC 2 audit"
Claude + MCP: Uses explain_workflow with markdown format
# Workflow Explanation: Payment Processing
## Executive Summary
Purpose: Automatically responds to events for e-commerce operations |
Business Domain: e-commerce | Type: event_driven |
Data flows from Webhook → 8 transformations → PostgreSQL, Slack, Email |
Depends on 4 external services | Risk Level: MEDIUM
## Purpose Analysis
**Primary Purpose**: Automatically responds to events for e-commerce operations
**Business Domain**: e-commerce
**Workflow Type**: event_driven
**Confidence**: 85%
## Data Flow
Input Sources: Order Webhook
Transformations: Validate Order → Calculate Totals → Check Inventory
Output Destinations: Save Order (PostgreSQL), Notify Team (Slack), Email Customer
## Dependencies
External Services:
- PostgreSQL (database)
- Slack (messaging)
- SendGrid (email)
⚠️ Single Points of Failure:
- Database used by 2 nodes
- High-criticality credential affects 2 nodes
## Risk Assessment
**Overall Risk Level**: MEDIUM (Score: 4.8/10)
🔴 Data Loss Risks:
- [HIGH] Database operation without transaction management (Save Order)
🔐 Security Risks:
- [HIGH] 3 high-criticality credentials in use
⚠️ Performance Risks:
- [MEDIUM] No rate limiting on external API calls (Check Inventory)
🛠️ Mitigation Plan:
1. [HIGH] Add error handling and retry logic
2. [HIGH] Ensure credentials are rotated regularly
3. [MEDIUM] Add rate limiting to API calls
Perfect for: Audit documentation, onboarding, risk assessment
You: "Which workflows will be affected if api.stripe.com goes down?"
Claude + MCP: Uses map_dependencies for all workflows
Affected Workflows (3):
1. Payment Processing
- Nodes: Process Payment, Refund
- Severity: CRITICAL
2. Subscription Manager
- Nodes: Create Subscription, Cancel
- Severity: HIGH
3. Invoice Generator
- Nodes: Get Customer, Create Invoice
- Severity: MEDIUM
Total Impact: 3 workflows, 6 nodes affected
Recommendation: Plan maintenance window and notify stakeholders
8. Change Simulation & Safe Deployments (NEW!)
You: "I want to update the Payment Processing workflow to use the new Stripe API v2"
Claude + MCP: Uses simulate_workflow_changes
================================================================================
WORKFLOW CHANGE PLAN
================================================================================
Total Changes: 5
Risk Level: MEDIUM
🔴 BREAKING CHANGES
--------------------------------------------------------------------------------
• [HIGH] 1 connection(s) removed
Impact: Data flow will be interrupted
Recommendation: Verify that removed connections are intentional
🟡 STRUCTURAL CHANGES
--------------------------------------------------------------------------------
~ Modified node: 'Process Payment'
parameters.apiVersion: v1 → v2
parameters.endpoint: /charges → /payment_intents
credentials: stripe_v1 → stripe_v2
🟢 DATA FLOW CHANGES
--------------------------------------------------------------------------------
No data flow changes
⚠️ IMPACT ASSESSMENT
--------------------------------------------------------------------------------
Overall Risk Score: 4.5/10 (MEDIUM)
Dependency Impact:
• 1 new credential(s) required: stripe_v2
• 1 new external service(s) added: Stripe API v2
Downstream Impact:
• Changes will affect 2 workflow(s) that call this workflow
- Order Processing (calls this workflow)
- Refund Handler (calls this workflow)
💡 RECOMMENDATIONS
--------------------------------------------------------------------------------
🔑 Configure 1 new credential(s) before deployment
🌐 Verify connectivity to new external service(s): Stripe API v2
⚙️ Review and update 2 downstream workflow(s)
🧪 Run end-to-end tests to verify execution behavior
================================================================================
⚠️ WARNING: This change contains breaking changes!
Review carefully before applying.
================================================================================
DRY-RUN SIMULATION
================================================================================
✅ Simulation PASSED - Workflow is valid
**Estimated Performance:**
- Node Count: 8
- Duration: ~4.0s
- Memory: ~80MB
- Complexity: MEDIUM
You: "Create a change request for team review"
Claude + MCP: Uses create_change_request
✅ Change Request Created
**Request ID**: a3b4c5d6
**Workflow**: Payment Processing (8PyhAN1U4JvF5eSb)
**Status**: pending
**Requester**: dev.team
**Reason**: Migrate to Stripe API v2 for PSD2 compliance
**Created**: 2024-12-16T10:30:00Z
[Team Lead reviews and approves]
You: "Show me the change history for this workflow"
Claude + MCP: Uses get_change_history
# Change History
**Total Requests**: 12
Status Summary:
- applied: 10
- rejected: 1
- pending: 1
Recent Changes:
✅ Request a3b4c5d6
- Status: approved
- Requester: dev.team
- Reason: Migrate to Stripe API v2
- Reviewer: team.lead
- Comments: Approved - tested in staging environment
- Reviewed: 2024-12-16T14:20:00Z
✔️ Request x1y2z3a4
- Status: applied
- Requester: dev.team
- Reason: Add retry logic to payment processing
- Reviewer: senior.dev
- Applied: 2024-12-10T09:15:00Z
📦 Installation
1. Install Dependencies
cd n8n-workflow-builder
pip install -r requirements.txt
2. Configuration
# Create .env file
cp .env.example .env
# Get n8n API Key:
# 1. Go to your n8n instance: https://your-n8n-instance.com
# 2. Settings > API
# 3. "Create New API Key"
# 4. Copy key and paste into .env
Your .env should look like this:
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=n8n_api_abc123xyz...
3. Test Server
# Quick Test
python server.py
# Should not throw errors - if it does, check your .env!
4. Claude Desktop Integration
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Option 1: With Virtual Environment (Recommended)
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "/ABSOLUTE/PATH/TO/n8n-workflow-builder/.venv/bin/python",
"args": ["-m", "n8n_workflow_builder"],
"env": {
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your_api_key_here"
}
}
}
}
Option 2: With Global Python
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "python",
"args": [
"-m", "n8n_workflow_builder"
],
"env": {
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your_api_key_here",
"PYTHONPATH": "/ABSOLUTE/PATH/TO/n8n-workflow-builder/src"
}
}
}
}
Option 3: Direct with server.py (Legacy)
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "python",
"args": [
"/ABSOLUTE/PATH/TO/n8n-workflow-builder/src/n8n_workflow_builder/server.py"
],
"env": {
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your_api_key_here"
}
}
}
}
Option 4: With .env File (Most Secure)
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "/ABSOLUTE/PATH/TO/n8n-workflow-builder/.venv/bin/python",
"args": ["-m", "n8n_workflow_builder"],
"cwd": "/ABSOLUTE/PATH/TO/n8n-workflow-builder"
}
}
}
With this option, credentials are read from the .env file.
IMPORTANT:
- Replace
/ABSOLUTE/PATH/TO/with your actual path! - Windows users: Use
\\or/as path separator - Windows Python path:
.venv\Scripts\python.exeinstead of.venv/bin/python
5. Restart Claude Desktop
Completely quit and reopen - then the MCP server should be available! 🎉
🎮 Usage Examples
Get Node Suggestions
You: "Suggest nodes for: API endpoint that validates data and writes to a database"
Claude uses: suggest_workflow_nodes
→ You get suggestions for Webhook, IF, HTTP Request, Postgres, etc.
Generate Complete Workflow
You: "Generate a workflow for daily sales reports from Postgres to Slack"
Claude uses: generate_workflow_template
→ You get complete structure with all nodes, connections, and config tips
Analyze Workflow
You: "Analyze my workflow with ID abc-123"
Claude uses: analyze_workflow
→ Finds issues, security problems, gives optimization suggestions
Explore Node Details
You: "Explain the HTTP Request node"
Claude uses: explain_node
→ You get detailed explanation, use cases, best practices, examples
Debug Errors
You: "My workflow throws: Error 401 Unauthorized"
Claude uses: debug_workflow_error
→ You get troubleshooting steps, likely causes, solutions
List Workflows
You: "Show me all active workflows"
Claude uses: list_workflows
→ List of all workflows with status, node count, update date
Execute Workflow
You: "Execute workflow 'Test API' with input {userId: 123}"
Claude uses: execute_workflow
→ Workflow is triggered, you see execution status
Create Workflow
You: "Create a workflow called 'Test API' with a manual trigger and HTTP request node"
Claude uses: create_workflow
→ Workflow is created with all nodes and connections
→ Returns workflow ID and next steps
Edit Workflow
You: "Rename workflow abc-123 to 'Production Data Sync'"
Claude uses: update_workflow
→ Workflow is renamed
Get Template Recommendations (NEW!)
You: "Recommend templates for sending automated email notifications"
Claude uses: recommend_templates
→ Gets AI-powered recommendations with relevance scores:
1. Email Automation & Processing (68% match) - Intermediate
2. Multi-Channel Notification System (54% match) - Beginner
3. Global Error Handler (42% match) - Intermediate
Browse Template Library (NEW!)
You: "Show me all templates for API development"
Claude uses: get_templates_by_category (category: "api")
→ Lists:
- Simple API Endpoint (Beginner)
- API Rate Limiter & Queue (Advanced)
Search Templates (NEW!)
You: "Find templates about database sync"
Claude uses: search_templates
→ Finds all templates containing 'database' or 'sync'
Get Template Details (NEW!)
You: "Show me details for the notification_system template"
Claude uses: get_template_details
→ Complete template info:
- Node structure
- Implementation guide
- Estimated time: 20 minutes
- Use cases and best practices
Semantic Workflow Analysis (NEW!)
You: "Analyze workflow 'Payment Processing' for logic issues"
Claude uses: analyze_workflow_semantics
→ Deep semantic analysis report:
🚨 Critical Issues:
- SplitInBatches without completion loop (Node: Split Orders)
- Hardcoded API key detected (Node: Payment Gateway)
⚠️ High Priority:
- HTTP Request without retry logic (Node: Payment Gateway)
- IF node without false path (Node: Check Amount)
- Webhook without authentication (Node: Webhook Trigger)
💡 Recommendations:
- Add error handling for external API calls
- Consolidate 3 consecutive Set nodes for better performance
🤖 LLM Fixes: Copy-paste ready code for each issue
Get Execution Details
You: "Show me details for execution 47885"
Claude uses: get_execution_details
→ Shows complete node input/output data, errors, status, etc.
Important: To see execution data, the following options must be enabled in n8n Settings > Executions:
- ✅ Save manual executions
- ✅ Save execution progress
Context & State Management
You: "What workflow was I working on?"
Claude uses: get_session_state
→ Shows active workflow, recent workflows, and action history
You: "Analyze the current workflow"
Claude: Uses the last active workflow automatically
You: "Show me my recent workflows"
Claude uses: get_recent_workflows
→ List of last 10 workflows with timestamps
You: "What did I do in this session?"
Claude uses: get_session_history
→ Timeline of all actions (analyze, execute, update, etc.)
Workflow Validation
You: "Validate workflow abc-123 before deploying"
Claude uses: validate_workflow
→ Comprehensive validation report with errors and warnings
Example Output:
❌ Validation Failed
Errors (must fix):
1. Webhook node 'API Endpoint': No authentication enabled (security risk)
2. Node 'HTTP Request': Missing 'url' parameter
3. Duplicate node names found: Set
Warnings (should fix):
1. Nodes with default names (should be renamed): HTTP Request, Set
2. Postgres node 'Database Query': Using SELECT * (bad practice)
3. Workflow lacks error handling (Error Trigger node)
You: "Validate this workflow JSON before creating it"
Claude uses: validate_workflow_json
→ Validates structure before workflow creation
Intent Metadata (NEW!)
You: "Add intent to node 'Process Payment' explaining why it exists"
Claude uses: add_node_intent
→ Adds reason, assumptions, risks, alternatives to node metadata
You: "Show me all intent metadata for this workflow"
Claude uses: get_workflow_intents
→ Markdown report showing "why" behind each node
You: "Analyze intent coverage for workflow abc-123"
Claude uses: analyze_intent_coverage
→ Coverage: 75% (6/8 nodes documented)
→ Critical nodes missing intent: Payment Gateway, Error Handler
Migration Engine (NEW!)
You: "Check workflow abc123 for compatibility issues"
Claude uses: check_workflow_compatibility
→ Compatibility report with severity levels and recommendations
You: "What migrations are available for HTTP Request node?"
Claude uses: get_available_migrations
→ Lists all migration rules for HTTP Request (v2→v3, v3→v4)
You: "Migrate workflow abc123 to latest versions"
Claude uses: migrate_workflow
→ Applies migrations, validates changes, updates workflow
You: "Show preview of migration for workflow xyz789"
Claude uses: get_migration_preview
→ Before/after comparison without applying changes
You: "Check all workflows for compatibility"
Claude uses: batch_check_compatibility
→ Summary: X compatible, Y deprecated, Z breaking
→ Prioritized list of workflows needing updates
Execution Monitoring (NEW!)
You: "Watch the execution of workflow 'API Sync'"
Claude uses: watch_workflow_execution
→ Real-time status with simplified error messages if failed
You: "Get detailed error context for execution 47885"
Claude uses: get_execution_error_context
→ Full error context: node, input, output, error details
→ Simplified error message for AI consumption
→ Fix suggestions with confidence scores
You: "Analyze error patterns for workflow 'Payment Processing'"
Claude uses: analyze_execution_errors (with workflow_id)
→ Success rate: 78% (78/100 executions)
→ Most common errors:
1. "Timeout Error" in node "External API" (12 occurrences)
2. "401 Unauthorized" in node "Auth Check" (10 occurrences)
AI Error Analysis & Feedback
You: "My workflow failed with execution 12345, what went wrong?"
Claude uses: analyze_execution_errors (with execution_id)
→ AI-friendly error analysis with root cause and fixes
Example Output:
🔍 Execution Error Analysis: API Data Sync
❌ Status: Execution failed
🎯 Root Cause: Authentication/Authorization Error
🔴 Errors Detected:
1. Node: `Fetch User Data` - 401 Unauthorized
🤖 AI Guidance:
When generating workflows, ensure:
1. Use credential references: {{$credentials.name}} not hardcoded values
2. Specify correct authentication type (Bearer, Basic, OAuth)
3. Test credentials before deploying
📝 Fix Examples:
❌ Wrong: "apiKey": "sk-abc123"
✅ Correct: "authentication": "predefinedCredentialType"
You: "Get improvement suggestions for failed workflow"
Claude uses: get_workflow_improvement_suggestions
→ Node-specific fix recommendations
Explainability (NEW!)
You: "Explain the 'Payment Processing' workflow"
Claude uses: explain_workflow
→ Complete documentation: purpose, data flow, dependencies, risks
→ Available formats: markdown (default), json, text
You: "What is the purpose of workflow abc-123?"
Claude uses: get_workflow_purpose
→ Business domain, workflow type, trigger description, expected outcomes
You: "Trace the data flow in this workflow"
Claude uses: trace_data_flow
→ Input sources, transformations, output destinations, critical paths
You: "Show me all dependencies for this workflow"
Claude uses: map_dependencies
→ Internal workflows, external services, credentials, single points of failure
You: "Assess the risks in this workflow"
Claude uses: analyze_workflow_risks
→ 5 risk categories with mitigation plan
→ Overall risk score and level
🧠 Knowledge Base
The server knows these node categories:
Triggers
- Webhook: API endpoints, external integrations
- Schedule: Cron jobs, periodic tasks
- Manual: Testing, manual interventions
Logic Nodes
- IF: Conditional branching
- Switch: Multi-way branching
- Merge: Combine data streams
- Code: Custom JavaScript/Python
Data Operations
- HTTP Request: API calls
- Set: Data transformation
- Function: Complex data processing
Storage
- Postgres: Relational database
- Redis: Caching, session storage
Integrations
- Slack: Messaging & notifications
- Telegram: Bot integration
- Gmail: Email automation
🛠️ Advanced Features
Custom Templates
The server comes with predefined templates:
api_endpoint: Simple REST APIscheduled_report: Daily/hourly reportsdata_sync: Database synchronization
Security Checks
- Finds hardcoded credentials
- Warns about missing authentication
- Checks for insecure patterns
Performance Analysis
- Calculate workflow complexity
- Detect oversized workflows
- Suggest splits for better maintainability
💾 State File
The server stores session state in ~/.n8n_workflow_builder_state.json. This file contains:
- Currently active workflow
- Recent workflows (last 10)
- Session history (last 50 actions)
- Timestamps
This allows the server to maintain context between Claude conversations!
To reset state: Use the clear_session_state tool or delete the file manually:
rm ~/.n8n_workflow_builder_state.json
🐛 Troubleshooting
Server Won't Start
# Check Python version (should be 3.11+)
python --version
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
# Check .env
cat .env
# Should contain N8N_API_URL and N8N_API_KEY
"Authentication failed"
- Check if your API key is correct
- Go to n8n Settings > API and create a new key
- Make sure there are no spaces in the key
"Connection refused"
- Is your n8n instance reachable?
- Check:
curl https://your-n8n-instance.com/healthz - Firewall/VPN might be blocking
Claude Desktop Doesn't Recognize Server
- Completely quit Claude (also in background!)
- Check config file (valid JSON?)
- Paths absolute (not relative!)
- Restart Claude
- Check in Claude: Settings > Developer > MCP Servers
💡 Pro Tips
1. Workflow Naming
- Always rename nodes! "HTTP Request 1" is bad, "Fetch User Data" is good
- Use prefixes for categories: "[API] Get Users", "[DB] Insert Record"
2. Error Handling
- Always add error handling for critical workflows
- Use "Error Trigger" node for global error handling
- Log errors in Slack/Telegram for monitoring
3. Testing
- Always develop with "Manual Trigger" instead of direct webhook
- Use "Pinned Data" for consistent tests
- Split production/development workflows
4. Performance
- Batch API calls where possible
- Use Redis for caching
- Avoid too many sequential HTTP requests
5. Security
- NEVER hardcode API keys - always use credentials
- Enable webhook authentication
- Only store sensitive data encrypted
🔄 State Management Deep Dive
For detailed information about the state management and context tracking system, see:
- State Management Documentation - Complete guide
- State File Example - Example state file
Quick summary:
- Automatically tracks active workflow
- Remembers last 10 workflows
- Logs last 50 actions with timestamps
- Persists between Claude sessions
- Stored in
~/.n8n_workflow_builder_state.json
✅ Workflow Validation Deep Dive
For detailed information about the validation system, see:
- Validation Documentation - Complete validation guide
Quick summary:
- 3-layer validation: Schema, Semantics, Parameters
- 30+ validation rules
- Security checks (credentials, authentication, SQL injection)
- Node-specific parameter validation
- Comprehensive error/warning reports
- Validates before deployment
🤖 AI Feedback Deep Dive
For detailed information about the AI feedback system, see:
- AI Feedback Documentation - Complete AI feedback guide
Quick summary:
- Intelligent error pattern recognition
- Root cause identification (6+ error types)
- AI-friendly structured feedback
- Fix examples (wrong vs. correct)
- Workflow improvement suggestions
- Learning loop for AI agents
🔒 RBAC & Multi-Tenant Security Deep Dive
For detailed information about the security system, see:
- RBAC & Security Documentation - Complete enterprise security guide
Quick summary:
- 5 role types (Admin, Developer, Operator, Viewer, Auditor)
- 20+ granular permissions
- Multi-tenant isolation (separate workflows per tenant)
- Approval workflows for critical operations
- Comprehensive audit logging (SOC2, ISO27001, GDPR ready)
- Cannot approve own requests (separation of duties)
RBAC Usage Examples
You: "Show me the RBAC status"
Claude uses: rbac_get_status
→ Shows users, roles, tenants, pending approvals, audit log
You: "Add user 'bob' as developer in tenant 'acme-corp'"
Claude uses: rbac_add_user
→ Creates user with developer permissions
You: "Check if bob can delete workflows"
Claude uses: rbac_check_permission
→ Shows if developer role has workflow.delete permission
You: "Bob wants to delete workflow abc-123, create approval request"
Claude uses: rbac_create_approval_request
→ Creates pending request for admin approval
You: "Approve request approval-123 as alice"
Claude uses: rbac_approve_request
→ Admin approves, operation can proceed
You: "Show audit log for last 24 hours"
Claude uses: rbac_get_audit_log
→ Shows all security events with timestamps
Enterprise Features
✅ Role-Based Access Control
- 5 built-in roles with predefined permissions
- Granular permission checks before operations
- Flexible role assignment per user
✅ Multi-Tenant Isolation
- Complete data segregation between tenants
- Separate workflows, users, audit logs per tenant
- Tenant-based access control
✅ Approval Workflows
- 4 critical operations require approval
- Cannot approve own requests
- Full audit trail of approval decisions
✅ Audit Logging
- Last 500 security events stored
- Filter by user, action, timestamp
- Compliance-ready (SOC2, ISO27001, GDPR)
✅ Security by Design
- Least privilege principle
- Separation of duties
- Immutable audit logs
- No self-approval
🔄 Updates & Extensions
Add Custom Nodes to Knowledge Base
Edit server.py and extend NODE_KNOWLEDGE:
NODE_KNOWLEDGE["integrations"]["notion"] = {
"name": "Notion",
"desc": "Notion database integration",
"use_cases": ["Knowledge base", "Project management"],
"best_practices": ["Use database IDs", "Batch updates"]
}
Create Custom Templates
Edit WORKFLOW_TEMPLATES in server.py:
WORKFLOW_TEMPLATES["my_template"] = {
"name": "My Custom Template",
"nodes": [...],
"connections": "custom"
}
📊 API Reference
The server uses the official n8n REST API:
- Base URL:
https://your-n8n-instance.com/api/v1 - Docs: https://docs.n8n.io/api/
Used endpoints:
GET /workflows- List workflowsGET /workflows/{id}- Get workflow detailsPOST /workflows- Create workflowPUT /workflows/{id}- Update workflowPOST /workflows/{id}/run- Execute workflowGET /executions- Get execution historyGET /executions/{id}- Get execution details
🤝 Contributing
Ideas? Issues? PRs welcome! 🎉
📊 Drift Detection Deep Dive
For detailed information about the drift detection system, see:
- Drift Detection Documentation - Complete drift detection guide
Quick summary:
- Temporal comparison: baseline (first 30%) vs current (last 30%) execution periods
- 4 drift patterns: success rate, performance, new errors, error frequency
- Change point detection: finds when metrics changed significantly
- 7 root cause types: rate limits, dependency failures, schema changes, credentials, resource exhaustion, logic bugs, config drift
- Confidence scoring: 0.0-1.0 for all analysis
- Actionable fixes: error-type specific with testing recommendations
💭 Intent Metadata Deep Dive
For detailed information about the intent metadata system, see:
- Intent Metadata Documentation - Complete intent system guide
Quick summary:
- "Why" documentation for each workflow node
- 5 fields: reason, assumption, risk, alternative, dependency
- AI context continuity across iterations
- Coverage analysis and suggestions
- Stored in node metadata (n8n native field)
🔄 Execution Monitoring Deep Dive
For detailed information about execution monitoring, see:
- Execution Monitoring Documentation - Complete monitoring guide
Quick summary:
- Real-time execution watching with error detection
- Error simplification for AI consumption
- Context extraction (node, input, output, error)
- Pattern analysis across multiple executions
- Fix suggestions with confidence scores
🔄 Migration Engine Deep Dive
For detailed information about the migration system, see:
- Migration Engine Documentation - Complete migration guide
Quick summary:
- Automatic node compatibility checking
- Rule-based transformations for node version upgrades
- 7 built-in migration rules (HTTP Request, Postgres, Slack, Function, Webhook, Set)
- Dry-run mode for safe previews
- Batch compatibility checks across all workflows
- Severity-based issue prioritization (critical, high, medium, low)
- Validates migrations to prevent data loss
📖 Explainability Layer Deep Dive
For detailed information about the explainability layer, see:
- Explainability Layer Documentation - Complete explainability guide
Quick summary:
- Automatic, audit-ready workflow documentation
- Purpose analysis with business domain classification (10 domains)
- Complete data flow tracing (sources → transformations → sinks)
- Dependency mapping (internal workflows + 25+ external services)
- 5-category risk assessment (data loss, security, performance, availability, compliance)
- Multi-format export (Markdown/JSON/Plain Text)
- Zero configuration, works with any workflow
🔮 Change Simulation & Approval Deep Dive
For detailed information about change simulation and approval workflows, see:
- Change Simulation Documentation - Complete change simulation guide
Quick summary:
- Terraform-style workflow change preview (like
terraform plan) - Breaking change detection (trigger removal, connection changes, output nodes)
- Multi-dimensional impact analysis (5 dimensions)
- Risk scoring algorithm (0-10 scale)
- Dry-run validation (structure + semantics + performance)
- Approval workflow with audit trail
- Performance estimation and recommendations
6 New MCP Tools:
simulate_workflow_changes- Preview changes with terraform-style plancompare_workflows- Side-by-side workflow comparisonanalyze_change_impact- Multi-dimensional impact analysiscreate_change_request- Create approval requestreview_change_request- Approve/reject changesget_change_history- View workflow change history
🚀 Intelligent Template System v2.0
For detailed information about the template system, see:
- Template System Documentation - Complete intelligent template system guide
Quick summary:
- Multi-source template adapters (n8n official, GitHub, local files)
- AI-powered template recommendations based on intent understanding
- Semantic matching beyond simple keywords
- Template quality scoring and ranking
- Automatic caching and deduplication
- Zero configuration required
📦 Version History
See CHANGELOG.md for complete version history and release notes.
Latest Release: v1.22.1 - Complete n8n 2.2.6 Node Coverage
Recent Releases
- v1.22.1 - Complete node coverage with 61 nodes (Jan 2025)
- v1.22.0 - n8n 2.2.6 compatibility (Jan 2025)
- v1.21.0 - Version tracking system (Dec 2024)
- v1.20.0 - Documentation access & node replacement (Dec 2024)
📁 Example Workflows
Check out the examples/ directory for ready-to-use workflow examples:
- Simple API Endpoint - Basic webhook with JSON response
- Daily Sales Report - Scheduled Postgres query → Slack notification
- User Registration API - Complete CRUD with validation and error handling
Each example includes:
- ✅ Complete working workflow JSON
- ✅ Documentation and setup instructions
- ✅ Best practices and security tips
- ✅ SQL schemas and configuration examples
📝 License
MIT - Do whatever you want!
🙏 Credits
- Built for awesome n8n automation 🚀
- Powered by Claude MCP ⚡
- Made with ❤️ for DevOps Engineers
Happy Automating! 🎊
For questions or problems: Just ask Claude! 😉