One-Stop-Shop-N8N-MCP

Zevas1993/One-Stop-Shop-N8N-MCP

3.2

If you are the rightful owner of One-Stop-Shop-N8N-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

n8n-MCP is a comprehensive Model Context Protocol server designed to provide AI agents with full access to n8n workflow automation, enabling them to discover, create, manage, and verify workflows efficiently.

Tools

  1. get_node_summary

    Provides an ultra-light overview of nodes, perfect for discovery.

  2. n8n_create_workflow

    Creates new workflows from JSON data.

  3. quick_workflow_check

    Performs fast error detection with screenshots.

One-Stop-Shop-N8N-MCP: Complete AI Agent Server for n8n Automation

License: MIT Version Docker

A complete Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n workflow automation. Features the full workflow lifecycle: discover nodes, create workflows, execute them, and validate they work correctly.

šŸŽÆ Overview

One-Stop-Shop-N8N-MCP is the complete solution for AI-powered n8n automation. It provides AI agents with everything they need to understand, create, manage, and verify n8n workflows - all from a single, easy-to-deploy server.

šŸš€ Key Features

  • šŸ“š 526 n8n nodes - Complete coverage from n8n-nodes-base (435 nodes) and @n8n/n8n-nodes-langchain (91 nodes)
  • šŸ”„ Progressive disclosure - AI agents get exactly the information they need (1KB to 50KB responses)
  • šŸ”§ Complete workflow lifecycle - Create, update, execute, and validate workflows via n8n API
  • šŸ¤– AI-optimized tools - 39 specialized tools designed for AI agent efficiency
  • šŸ›”ļø Bulletproof reliability - 100% working tools with robust error handling (39/39 tools pass)
  • āš” Universal compatibility - Works with any Node.js version (automatic database adapter)
  • šŸ³ Docker-ready - Complete solution with bundled dependencies

šŸŽÆ What Makes This Special

This is the only MCP server that provides AI agents with:

  1. Complete n8n knowledge - Every node, property, and operation documented
  2. Workflow creation & management - Full API integration for workflow operations
  3. Progressive disclosure - Choose information granularity to prevent AI overload
  4. Single unified interface - No need to manage multiple servers
  5. Ready-to-run Docker - Just clone and run, no complex setup required

šŸš€ Quick Start Guide

šŸ³ Docker Deployment (Recommended)

Prerequisites: Docker and Docker Compose installed on your system

Step 1: Clone the Repository
git clone https://github.com/Zevas1993/One-Stop-Shop-N8N-MCP.git
cd One-Stop-Shop-N8N-MCP
Step 2: Configure Environment
# Copy the example environment file
cp .env.example .env

# Edit with your settings (optional - defaults work fine)
nano .env

# Key settings to configure:
# AUTH_TOKEN=your-secure-token-here (generate with: openssl rand -base64 32)
# MCP_MODE=http (for Docker) or stdio (for local)
# N8N_API_URL=http://localhost:5678 (optional, for workflow management)
# N8N_API_KEY=your-n8n-api-key (optional, for workflow management)
Step 3: Run with Docker Compose
# Start the server
docker compose up -d

# Check server status
docker compose logs -f

# You should see: "n8n MCP Fixed HTTP Server running on 0.0.0.0:3000"
Step 4: Test the Server
# Test health endpoint
curl http://localhost:3000/health

# Test tool count
curl -H "Authorization: Bearer test-browser-automation-token" \
  http://localhost:3000/mcp -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
  | grep -o '"name"' | wc -l

# Should return: 39
Step 5: Connect to Claude Desktop

Add to your ~/.claude_desktop_config.json:

For Local Development (stdio mode - Current Working Setup):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\YourUsername\\Documents\\MCP-Servers\\One-Stop-Shop-N8N-MCP\\claude-stdio-bridge.js"
      ],
      "env": {
        "NODE_DB_PATH": "C:\\Users\\YourUsername\\Documents\\MCP-Servers\\One-Stop-Shop-N8N-MCP\\data\\nodes.db",
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-n8n-api-key-here"
      }
    }
  }
}

For Docker (HTTP mode - Alternative):

{
  "mcpServers": {
    "n8n-mcp-docker": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote@latest",
        "connect",
        "http://localhost:3000/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "test-browser-automation-token"
      }
    }
  }
}

Alternative: Use the provided config file:

# Copy the ready-made configuration
cp claude-desktop-config.json ~/.claude_desktop_config.json

# Restart Claude Desktop to load the new configuration

For Docker (stdio mode - advanced):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "n8n-mcp-unified", "node", "dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio"
      }
    }
  }
}

šŸ› ļø Local Development Setup

For developers who want to modify the code:

# Clone and install
git clone https://github.com/Zevas1993/One-Stop-Shop-N8N-MCP.git
cd One-Stop-Shop-N8N-MCP
npm install

# Build the project
npm run build

# Initialize database (downloads n8n node information)
npm run rebuild

# Start server in stdio mode
npm start

šŸ”§ Configuration Guide

šŸ“‹ Environment Variables

The server uses environment variables for configuration. Key settings:

Basic Configuration
# Server mode - stdio for Claude Desktop, http for remote access
MCP_MODE=http
PORT=3000

# Authentication token (required for HTTP mode)
AUTH_TOKEN=test-browser-automation-token

# Database path
NODE_DB_PATH=/app/data/nodes.db

# Logging level
LOG_LEVEL=info
n8n API Integration (Optional - Enables 11 Workflow Management Tools)
# Enable workflow management tools by providing n8n API access
N8N_API_URL=http://localhost:5678
N8N_API_KEY=your-n8n-api-key

# Optional: API timeout and retries
N8N_API_TIMEOUT=30000
N8N_API_MAX_RETRIES=3
How to Get n8n API Key
  1. Open your n8n instance (e.g., http://localhost:5678)
  2. Go to Settings ā†’ API
  3. Click Create API Key
  4. Copy the key and add it to your .env file

šŸ”— Integration Examples

Claude Desktop - HTTP Mode (Recommended)
{
  "mcpServers": {
    "n8n-mcp-docker": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote@latest",
        "connect",
        "http://localhost:3000/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "test-browser-automation-token"
      }
    }
  }
}
Claude Desktop - stdio Mode (Local Binary)
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/path/to/One-Stop-Shop-N8N-MCP/dist/mcp/index.js"],
      "env": {
        "MCP_MODE": "stdio"
      }
    }
  }
}

šŸ› ļø Available Tools (39 Total)

The server provides 39 specialized tools organized by category:

šŸ” Node Discovery & Information (9 tools)

  • list_nodes - List all available n8n nodes with filtering
  • find_nodes - Search nodes by keywords or category
  • get_node_info - Full node details (essentials ~5KB, complete ~50KB)
  • get_node_summary - Ultra-light overview (<1KB)
  • get_node_essentials - Only essential properties with examples
  • search_nodes - Full-text search across all node documentation
  • search_node_properties - Search for specific properties within a node
  • get_node_as_tool_info - Get information about using nodes as AI tools
  • list_ai_tools - List all AI-capable nodes

šŸ—ļø Workflow Management Tools (11 tools - Requires n8n API)

  • n8n_create_workflow - Create new workflows from JSON
  • n8n_get_workflow - Get workflow by ID (multiple detail levels)
  • n8n_update_full_workflow - Complete workflow replacement
  • n8n_update_partial_workflow - Diff-based workflow updates
  • n8n_delete_workflow - Remove workflows permanently
  • n8n_list_workflows - Browse existing workflows with filters
  • n8n_trigger_webhook_workflow - Execute workflows via webhooks
  • n8n_get_execution - Get execution details by ID
  • n8n_list_executions - Browse execution history
  • n8n_delete_execution - Delete execution records
  • n8n_system - Health checks and diagnostics

šŸ”§ Configuration & Validation Tools (11 tools)

  • get_node_config - Pre-configured node settings for common tasks
  • get_node_for_task - Get node configuration for specific tasks
  • list_tasks - List all available task templates
  • validate_node - Node configuration validation (minimal/full modes)
  • validate_node_operation - Operation-aware node validation
  • validate_node_minimal - Quick validation for required fields
  • validate_workflow - Complete workflow validation (multiple modes)
  • validate_workflow_connections - Check workflow structure and connections
  • validate_workflow_expressions - Validate all n8n expressions
  • validate_before_adding - Pre-flight workflow validation
  • check_compatibility - Quick node connection validation

šŸ“‹ Template & Utility Tools (8 tools)

  • get_template - Get complete workflow JSON by template ID
  • list_node_templates - Find workflow templates using specific nodes
  • get_templates_for_task - Get curated templates for common tasks
  • get_workflow_guide - Scenario-based guidance for common patterns
  • get_property_dependencies - Analyze property dependencies
  • get_node_documentation - Get parsed documentation from n8n-docs
  • get_database_statistics - Server metrics and performance data
  • n8n_validate_workflow - Validate workflow from n8n instance by ID

šŸŽÆ Common Usage Patterns

šŸ” Node Discovery & Learning

AI Agent: "I need to create a workflow that processes webhooks"
1. find_nodes({"query": "webhook"}) -> Find webhook nodes
2. get_node_summary({"nodeType": "nodes-base.webhook"}) -> Quick overview (<1KB)
3. get_node_essentials({"nodeType": "nodes-base.webhook"}) -> Essential configuration (~5KB)

šŸ—ļø Workflow Creation

AI Agent: "Create a webhook-to-slack workflow"
1. n8n_create_workflow({"name": "Webhook to Slack", "nodes": [...], "connections": {...}})
2. validate_workflow({"workflow": {...}, "mode": "quick"}) -> Validate configuration
3. n8n_get_workflow({"id": "workflow-id"}) -> Confirm creation

šŸ”§ Workflow Updates

AI Agent: "Add a HTTP Request node to existing workflow"
1. n8n_update_partial_workflow({"id": "workflow-id", "operations": [...]}) -> Use diff updates
2. validate_workflow({"workflow": {...}}) -> Ensure it's still valid
3. n8n_validate_workflow({"workflowId": "workflow-id"}) -> Validate from n8n instance

šŸ“‹ Template Usage

AI Agent: "Find templates for Slack automation"
1. get_templates_for_task({"task": "slack_integration"}) -> Search templates
2. get_template({"templateId": 123}) -> Get complete workflow JSON
3. n8n_create_workflow(template_json) -> Create from template

šŸ“Š Response Size Guide

Tools are designed with progressive disclosure for AI efficiency:

  • <1KB: Ultra-light summaries (get_node_summary) - Perfect for discovery
  • ~5KB: Essential information (get_node_essentials) - Common usage
  • ~50KB: Complete details (get_node_info complete mode) - Deep configuration
  • <2KB: Quick validations (validate_node_minimal) - Fast feedback

šŸ³ Docker Features

āœ… Complete Self-Contained Solution

  • All dependencies included - No external setup required
  • Universal Node.js compatibility - Works with any Node.js version
  • Auto-fallback database - Switches between better-sqlite3 and sql.js automatically
  • Pre-built database - 526 nodes ready to use

šŸš€ Optimized for Production

  • Ultra-lightweight - Optimized runtime image
  • Fast startup - Pre-built database included
  • Memory efficient - Intelligent cache management (512MB limit)
  • Security focused - Non-root user execution
  • Health checks - Built-in monitoring

šŸ“‹ Docker Commands

# Clone and start
git clone https://github.com/Zevas1993/One-Stop-Shop-N8N-MCP.git
cd One-Stop-Shop-N8N-MCP
docker compose up -d

# Check server health
docker compose logs -f

# Stop server
docker compose down

# Update and restart
git pull && docker compose up -d --build

# Test server
curl http://localhost:3000/health

šŸ”’ Security & Credentials

šŸ›”ļø Credential Protection

  • All credentials in environment variables - Never hardcoded
  • .env file is gitignored - Prevents accidental commits
  • Template provided - Copy .env.example to .env for safety

šŸ” Authentication Methods

  • HTTP mode: Bearer token authentication (AUTH_TOKEN)
  • n8n API: API key authentication (N8N_API_KEY)
  • Docker: Environment file management

šŸšØ Important Security Notes

  • Generate strong tokens: Use openssl rand -base64 32 for AUTH_TOKEN
  • Current default token: test-browser-automation-token (change for production!)
  • Secure n8n access: Use HTTPS for production n8n instances
  • Network security: Run in private networks when possible

šŸ› ļø Development Guide

šŸš€ Available Scripts

# Development
npm run dev          # Development mode with auto-reload
npm run build        # Build TypeScript
npm run test         # Run Jest tests
npm run typecheck    # TypeScript type checking
npm run lint         # Run linting

# Database Management
npm run rebuild      # Rebuild node database from n8n packages
npm run rebuild:local # Rebuild without GitHub dependencies
npm run validate     # Validate critical nodes work correctly

# Docker Development
docker compose up -d --build  # Build and start server
docker compose logs -f        # View logs

šŸ—ļø Architecture Overview

src/
ā”œā”€ā”€ mcp/
ā”‚   ā”œā”€ā”€ server.ts                    # Main MCP server (handles all 39 tools)
ā”‚   ā”œā”€ā”€ tools.ts                     # Node documentation tools (28 tools)
ā”‚   ā””ā”€ā”€ tools-n8n-manager.ts        # n8n API management tools (11 tools)
ā”œā”€ā”€ services/
ā”‚   ā”œā”€ā”€ node-documentation-service.ts # Node data service
ā”‚   ā”œā”€ā”€ workflow-validator.ts        # Workflow validation logic
ā”‚   ā””ā”€ā”€ enhanced-config-validator.ts # Node configuration validation
ā”œā”€ā”€ database/
ā”‚   ā”œā”€ā”€ database-adapter.ts          # Universal database compatibility
ā”‚   ā”œā”€ā”€ node-repository.ts           # Node data access layer
ā”‚   ā””ā”€ā”€ schema.sql                   # Database schema
ā””ā”€ā”€ utils/
    ā”œā”€ā”€ query-cache.ts               # Memory-efficient caching
    ā””ā”€ā”€ logger.ts                    # Logging utility

šŸ“ˆ Performance Metrics

Current Database Statistics:

  • 526 nodes successfully loaded (100% coverage)
  • 435 nodes from n8n-nodes-base package
  • 91 nodes from @n8n/n8n-nodes-langchain package
  • 470 nodes with documentation (89% coverage)
  • 263 AI-capable tools detected and catalogued
  • 104 trigger nodes for workflow initiation
  • 128 versioned nodes with multiple versions

Server Performance:

  • Auto-fallback database system ensures 100% uptime
  • <2ms average response time for cached queries
  • 33% cache hit rate (improves with consistent usage)
  • Memory usage: 256MB-512MB (Docker limits)

šŸ”„ Recent Updates (v2.7.5)

āœ… Tool Reliability Enhancement

  • 39 tools working - 100% success rate, removed 2 broken template search tools
  • Fixed parameter inconsistencies - n8n_validate_workflow now uses correct workflowId parameter
  • Enhanced error handling - All tools provide clear error messages
  • Improved documentation - Updated tool descriptions and examples

āœ… Workflow Management

  • Partial workflow updates - Only send the changes, not entire workflow
  • 80-90% token savings for AI agents
  • 13 diff operations - addNode, removeNode, updateNode, connections, etc.
  • Transaction safety - All operations succeed or all fail

āœ… Enhanced Progressive Disclosure

  • 3-tier information system (<1KB, ~5KB, ~50KB)
  • AI-optimized tool descriptions with size indicators
  • Choice-driven information access prevents cognitive overload

šŸ† Why Choose One-Stop-Shop-N8N-MCP?

  1. Complete Solution: Only server providing full n8n workflow lifecycle
  2. AI-Optimized: Progressive disclosure prevents information overload
  3. 100% Reliability: All 39 tools work perfectly on first try
  4. Universal Compatibility: Works with any Node.js version
  5. Production Ready: Docker deployment with health checks
  6. Actively Maintained: Regular updates and improvements
  7. Just Works: Clone and run - no complex setup

šŸ“„ License

This project is licensed under the MIT License - see the file for details.

šŸ™ Attribution

  • āœ… Free for any use (personal, commercial, etc.)
  • āœ… Modifications and distribution allowed
  • āœ… Can be included in commercial products
  • āœ… Can be hosted as a service

Attribution is appreciated but not required.

šŸ¤ Contributing

Contributions are welcome! This is a specialized MCP server designed for AI agents working with n8n. Please ensure:

  1. AI agent compatibility - Tools should be designed for AI consumption
  2. Progressive disclosure - Provide appropriate information granularity
  3. Documentation - Update README and tool descriptions
  4. Testing - Verify all tools work correctly (aim for 100% success rate)

šŸš€ Getting Started Checklist

Ready to use One-Stop-Shop-N8N-MCP? Follow this checklist:

āœ… Prerequisites

  • Docker and Docker Compose installed
  • n8n instance running (optional, for workflow management features)
  • Claude Desktop or MCP client ready

āœ… Quick Setup

  • Clone repository: git clone https://github.com/Zevas1993/One-Stop-Shop-N8N-MCP.git
  • Copy environment: cp .env.example .env
  • Generate secure token: openssl rand -base64 32 (replace in .env)
  • Start server: docker compose up -d
  • Check logs: docker compose logs -f
  • Look for: "n8n MCP Fixed HTTP Server running on 0.0.0.0:3000"

āœ… Health Check

  • Test health endpoint: curl http://localhost:3000/health
  • Verify tool count: Should return 39 tools
  • Check database: Should show 526 nodes loaded

āœ… Claude Desktop Integration

  • Add server to ~/.claude_desktop_config.json
  • Use HTTP mode with mcp-remote for best compatibility
  • Restart Claude Desktop
  • Test with: "List available n8n nodes for Slack"

āœ… Optional: n8n API Setup

  • Get n8n API key from Settings ā†’ API
  • Add N8N_API_URL and N8N_API_KEY to .env
  • Restart container: docker compose up -d
  • Verify workflow tools: Should have 11 additional n8n management tools

šŸ› ļø Troubleshooting

Memory Pressure and Timeout Issues

If you encounter "MCP server connection + listTools timed out after 60 seconds" or memory pressure warnings:

Problem: The full MCP server loads all 526 nodes into memory at startup, causing timeouts.

Solution: Use the stdio bridge for live Docker queries:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": [
        "path/to/One-Stop-Shop-N8N-MCP/claude-stdio-bridge.js"
      ],
      "env": {
        "NODE_DB_PATH": "path/to/One-Stop-Shop-N8N-MCP/data/nodes.db",
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Benefits:

  • āœ… No memory pressure - Queries live Docker container instead of loading database
  • āœ… Fast startup - Connects in <10 seconds instead of timing out
  • āœ… All tools available - Full workflow management capabilities preserved
  • āœ… Real-time data - Always pulls latest node information from n8n

Other Common Issues

Database not found: Run npm run rebuild to create the nodes database.

Docker container errors: Ensure n8n container is running and accessible.

Tool failures: Check that N8N_API_URL and N8N_API_KEY are correctly configured.

šŸŽÆ The Complete n8n AI Agent Solution - Discover, Create, and Manage workflows with a single unified MCP server.

Ready to get started? Just git clone and docker compose up -d! šŸš€