n8n-mcp-enhanced by eekfonky - MCP Server

n8n-MCP Enhanced 🤖⚡

Comprehensive n8n MCP server with 87+ tools and hierarchical agent system for intelligent workflow automation

A complete Model Context Protocol (MCP) server that provides AI assistants with extensive access to n8n's entire ecosystem through a sophisticated 7-agent hierarchical system. Designed for seamless integration with Claude Code and the broader MCP ecosystem.

🎯 What This Is

The definitive n8n MCP solution - comprehensive tools, intelligent agents, and full ecosystem integration.

🧠 7-Agent Hierarchical System: Claude Opus/Sonnet/Haiku specialists with intelligent delegation
🛠️ 87+ MCP Tools: Complete n8n ecosystem coverage + advanced workflow management
📚 525+ Node Database: Every n8n node with validation, documentation, and AI capabilities
🔧 MCP Ecosystem Ready: Optimized for Sequential Thinking, Memory, Filesystem, Context7 integration
⚡ Production Ready: Full workflow lifecycle management and deployment capabilities

🏗️ Architecture

Hierarchical Agent System

TIER 1: MASTER ORCHESTRATOR (Claude Opus)
├─ n8n-workflow-architect - Strategic planning, complex architecture, multi-agent coordination

TIER 2: CORE SPECIALISTS (Claude Sonnet)
├─ n8n-validator - Security analysis, multi-level validation, compliance checking
├─ n8n-integration-specialist - Authentication, connectivity, OAuth flows, API setup
└─ n8n-node-specialist - 525+ node expertise, AI/ML workflows, performance optimization

TIER 3: RESEARCH SPECIALISTS (Claude Haiku)
├─ n8n-assistant - Quick research, essential information synthesis
├─ n8n-docs-specialist - Documentation, setup guides, configuration examples
└─ n8n-community-specialist - AI/ML patterns, community packages, experimental approaches

Complete Tool Ecosystem (87+ Tools)

Core n8n Tools (25 tools):

Discovery: search_nodes, list_nodes, list_ai_tools, get_database_statistics
Configuration: get_node_info, get_node_essentials, get_node_documentation, search_node_properties
Validation: validate_node_operation, validate_workflow, validate_workflow_connections, validate_workflow_expressions
AI Integration: get_node_as_tool_info, get_property_dependencies
Agent Coordination: Task (intelligent delegation)

n8n Management Tools (47 tools) - Full workflow lifecycle:

Workflow Management: Create, update, delete, list, validate workflows
Execution Control: Execute, test, trigger, monitor, retry workflows
Import/Export: Backup, restore, duplicate, migrate workflows
System Integration: Credentials, tags, variables, webhooks, community packages
Analytics: Performance metrics, execution logs, usage statistics

n8n Core Integration (8 tools) - Advanced capabilities:

Expression Engine: n8n_evaluate_expression, n8n_test_expression_syntax
Validation Engine: n8n_validate_node_parameters, n8n_simulate_node_execution
Workflow Optimization: n8n_transform_workflow, n8n_generate_node_template

Documentation System (7 tools):

Comprehensive Guides: Tool documentation, setup instructions, best practices
Context-Aware Help: JavaScript/Python code node guides, troubleshooting

🚀 Quick Start

Prerequisites

Required MCP Ecosystem (for optimal performance):

# Essential MCPs (install these first)
claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory  
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Code
claude mcp add context7 -- npx -y @upstash/context7-mcp

Installation

🚀 Method 1: Direct MCP Installation (Simplest)

# Basic installation (stdio mode, no n8n API required)
claude mcp add @lexinet/n8n-mcp-enhanced

# With n8n API credentials (for workflow management)
# Note: URL is automatically normalized - just provide your n8n base URL
claude mcp add @lexinet/n8n-mcp-enhanced \
  --env N8N_API_URL="https://your-n8n-instance.com" \
  --env N8N_API_KEY="your-api-key-here"

# With additional configuration
claude mcp add @lexinet/n8n-mcp-enhanced \
  --env N8N_API_URL="https://your-n8n-instance.com" \
  --env N8N_API_KEY="your-api-key-here" \
  --env LOG_LEVEL="error" \
  --env DISABLE_CONSOLE_OUTPUT="true"

🚀 Method 2: NPM Global Install with Auto-Setup

npm install -g @lexinet/n8n-mcp-enhanced

This automatically installs:

✅ 7 n8n specialist agents → .claude/agents/ (current project)
✅ 5 MCP servers → Global/local Claude Code config (.claude.json)
✅ 87+ tools ready for use
✅ Complete ecosystem integration

⚠️ Note: After npm install, you'll still need to configure n8n API credentials for workflow management features:

Set N8N_API_URL and N8N_API_KEY in your environment or .env file
Without API credentials, only node discovery/documentation tools will work
Workflow creation, execution, and management require valid n8n API access

Manual Setup (Alternative)

# Install package only
npm install -g @lexinet/n8n-mcp-enhanced --no-scripts

# Run setup manually when ready
npm run setup

n8n API Integration (Optional but Recommended)

For complete workflow management capabilities:

export N8N_API_URL=https://your-n8n-instance.com
export N8N_API_KEY=your-api-key

📍 URL Auto-Normalization: The package automatically handles URL formatting:

✅ https://n8n.example.com → https://n8n.example.com/api/v1
✅ https://n8n.example.com/ → https://n8n.example.com/api/v1
✅ https://n8n.example.com/api → https://n8n.example.com/api/v1
✅ https://n8n.example.com/api/v1 → https://n8n.example.com/api/v1

No need to worry about trailing slashes or /api/v1 - just provide your base n8n URL!

🤖 Using the Enhanced Agent System

Master Orchestration (Full MCP Access)

Use the n8n-workflow-architect agent to design a comprehensive AI-powered customer support automation with multi-channel integration, sentiment analysis, and intelligent escalation

Specialized Expert Tasks

# Security & Validation
Ask the n8n-validator agent to perform a comprehensive security audit of this workflow including credential safety, data privacy, and compliance validation

# Authentication & Integration  
Have the n8n-integration-specialist agent set up OAuth 2.0 authentication for Gmail with proper scope management and refresh token handling

# Node Discovery & AI Workflows
Use the n8n-node-specialist agent to design an optimal AI/ML pipeline for real-time document processing and analysis

Quick Research & Documentation

# Fast Information Synthesis
n8n-assistant agent: quickly compare webhook trigger options for real-time data processing

# Comprehensive Setup Guides
n8n-docs-specialist agent: create complete setup documentation for Slack integration with error handling

# AI/ML & Community Solutions  
n8n-community-specialist agent: research latest AI workflow patterns and recommend optimal community packages

🔧 MCP Ecosystem Integration

Synergy Opportunities

Sequential Thinking + n8n-MCP: Complex workflow decomposition and strategic planning Memory + Patterns: Learn from successful integrations and store proven solutions
Filesystem + Templates: Workflow backup, template management, and code generation Context7 + Documentation: Real-time n8n updates combined with comprehensive local knowledge

Performance Enhancement

With full MCP ecosystem integration:

5x faster research: Context7 + Memory combination
10x better planning: Sequential Thinking + Architecture
3x more reliable: End-to-end validation and testing
Persistent learning: Memory across all agent interactions

🛠️ Development & Advanced Usage

Building from Source

git clone https://github.com/eekfonky/n8n-mcp-enhanced.git
cd n8n-mcp-enhanced
npm install
npm run build
npm run rebuild  # Builds node database
npm start        # Starts MCP server

Environment Configuration

# Core MCP Settings
MCP_MODE=stdio              # Optimized for Claude Code
LOG_LEVEL=error            # Minimal logging for production
DISABLE_CONSOLE_OUTPUT=true # Clean MCP communication

# n8n API Integration (Optional)
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key
N8N_WEBHOOK_BASE_URL=      # For webhook configuration

# Performance Optimization
NODE_ENV=production        # Production optimizations

Custom Agent Configuration

Agents are defined in .claude/agents/ with:

YAML frontmatter: Model selection (claude-opus/sonnet/haiku), tool access, descriptions
System prompts: Role definitions, expertise areas, delegation patterns
MCP Integration: Optimized tool usage and synergy patterns

📊 Capabilities Overview

n8n Knowledge Base

525+ Nodes: Complete n8n ecosystem coverage
AI/ML Integration: 263 AI-capable nodes with usage guidance
Community Packages: Installation and management capabilities
Validation Profiles: Minimal, runtime, ai-friendly, strict validation levels

Workflow Management

Complete Lifecycle: Design → Validate → Deploy → Monitor → Optimize
Multi-Environment: Development, staging, production workflow management
Security First: Credential management, compliance checking, audit trails
Performance Optimization: Execution monitoring, bottleneck identification

Integration Capabilities

525+ Platform Integrations: Every supported n8n node and service
Authentication Mastery: OAuth 2.0, API keys, JWT, custom auth schemes
Real-time Processing: Webhooks, triggers, event-driven automation
Batch Operations: Scheduled workflows, data synchronization, bulk processing

🎯 Design Philosophy

Comprehensive Enhancement (v3.0.0)

This system has evolved from a "lean" prototype into the definitive n8n MCP solution:

Enhanced Components:

✅ 87+ comprehensive MCP tools (vs. original 17)
✅ 7-agent hierarchical intelligence system
✅ Complete workflow lifecycle management
✅ Full MCP ecosystem integration
✅ Production-ready security and validation
✅ Advanced AI/ML workflow capabilities

Maintained Focus:

✅ MCP-first architecture optimized for Claude Code
✅ Intelligent agent coordination and delegation
✅ Performance-optimized tool usage patterns
✅ Comprehensive n8n ecosystem knowledge

🤝 Contributing

This project maintains focus on comprehensive n8n automation through MCP and intelligent agents.

Contribution Guidelines

MCP Tools: Enhancements to n8n integration capabilities
Agent Intelligence: Improvements to delegation and coordination patterns
Documentation: Keep tool counts and capabilities documentation accurate
Performance: Maintain fast response times and efficient resource usage

📄 License

MIT License - see LICENSE file for details.

🏆 Credits

Enhanced by eekfonky, based on excellent foundational work by Romuald Czlonkowski.

Evolution: From lean prototype to comprehensive n8n MCP ecosystem solution.

📚 Documentation

: Development quality and optimization status
: Complete tool inventory and agent specialization matrix
: Real-time documentation patterns
: Complete setup and optimization guide

Built for Claude Code users who demand comprehensive n8n automation with intelligent MCP integration. 🎯