MCP 服务器

n8n Workflow Builder

Enables AI-powered building, optimization, debugging, and management of n8n workflows directly from Claude. Features workflow analysis, execution monitoring, security audits, drift detection, and intelligent error debugging with best practices guidance.

README

🚀 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: active and tags fields 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 plan for 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.exe instead 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 API
scheduled_report: Daily/hourly reports
data_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 workflows
GET /workflows/{id} - Get workflow details
POST /workflows - Create workflow
PUT /workflows/{id} - Update workflow
POST /workflows/{id}/run - Execute workflow
GET /executions - Get execution history
GET /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 plan
compare_workflows - Side-by-side workflow comparison
analyze_change_impact - Multi-dimensional impact analysis
create_change_request - Create approval request
review_change_request - Approve/reject changes
get_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

Browse 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! 😉