n8n-MCP

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy locally or remotely to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.

Overview

n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:

• 📚 525 n8n nodes from both n8n-nodes-base and @n8n/n8n-nodes-langchain
• 🔧 Node properties - 99% coverage with detailed schemas
• ⚡ Node operations - 63.6% coverage of available actions
• 📄 Documentation - 87% coverage from official n8n docs
• 🤖 AI tools - 263 AI-capable nodes detected

Features

• Comprehensive Node Information: Access properties, operations, credentials, and documentation for all n8n nodes
• AI Tool Detection: Automatically identifies nodes with AI capabilities (usableAsTool)
• Versioned Node Support: Handles complex versioned nodes like HTTPRequest and Code
• Fast Search: SQLite with FTS5 for instant full-text search across all documentation
• MCP Protocol: Standard interface for AI assistants to query n8n knowledge
• Remote Deployment Ready: Production-ready HTTP server for multi-user services
• Universal Compatibility: Works with any Node.js version through automatic adapter fallback

Quick Start

Choose your deployment method:

🐳 Docker (Recommended)

# 1. Create environment file
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
echo "USE_FIXED_HTTP=true" >> .env

# 2. Start the server
docker compose up -d

# 3. Check health
curl http://localhost:3000/health

That's it! The server is running and ready for connections.

💻 Local Installation

Prerequisites:

• Node.js (any version - automatic fallback if needed)
• npm or yarn
• Git

# 1. Clone the repository
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

# 2. Clone n8n docs (optional but recommended)
git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs

# 3. Install and build
npm install
npm run build

# 4. Initialize database
npm run rebuild

# 5. Start the server
npm start          # stdio mode for Claude Desktop
npm run start:http # HTTP mode for remote access

🔧 Claude Desktop Configuration

For Local Installation (stdio mode) - Recommended

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "node",
      "args": ["/path/to/n8n-mcp/dist/mcp/index.js"],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "error",
        "MCP_MODE": "stdio",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

⚠️ Important: The environment variables above are required for proper stdio communication.

For Docker (stdio mode)

{
  "mcpServers": {
    "n8n-docker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-v", "n8n-mcp-data:/app/data",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

For Remote Server (HTTP mode)

For production deployments with HTTP mode, use the custom HTTP client:

{
  "mcpServers": {
    "n8n-remote": {
      "command": "node",
      "args": [
        "/path/to/n8n-mcp/scripts/mcp-http-client.js",
        "http://your-server.com:3000/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-auth-token"
      }
    }
  }
}

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

⚠️ Note: After editing, restart Claude Desktop to apply changes.

🚀 Remote Deployment

Production HTTP Server

For multi-user services and remote deployments:

# 1. Set environment variables
export AUTH_TOKEN="your-secure-token-min-32-chars"
export USE_FIXED_HTTP=true
export MCP_MODE=http
export PORT=3000

# 2. Start with Docker
docker run -d \
  --name n8n-mcp \
  --restart unless-stopped \
  -e MCP_MODE=$MCP_MODE \
  -e USE_FIXED_HTTP=$USE_FIXED_HTTP \
  -e AUTH_TOKEN=$AUTH_TOKEN \
  -p $PORT:3000 \
  ghcr.io/czlonkowski/n8n-mcp:latest

# 3. Or use Docker Compose
docker compose up -d

Client Requirements

⚠️ Important: Remote connections require:

• Node.js 18+ installed locally (for mcp-remote)
• Or Claude Pro/Team/Enterprise (for native remote MCP support)

See HTTP Deployment Guide for detailed instructions.

📡 Available MCP Tools

Once connected, Claude can use these tools:

Tools

• list_nodes - List all n8n nodes with filtering options
• get_node_info - Get detailed information about a specific node
• search_nodes - Full-text search across all node documentation
• list_ai_tools - List all AI-capable nodes
• get_node_documentation - Get parsed documentation for a node
• get_database_statistics - View database metrics and coverage

Example Usage

// List all trigger nodes
list_nodes({ isTrigger: true })

// Get info about the HTTP Request node
get_node_info({ nodeType: "n8n-nodes-base.httpRequest" })

// Search for OAuth-related nodes
search_nodes({ query: "oauth authentication" })

// Find AI-capable tools
list_ai_tools()

// Get Slack node documentation
get_node_documentation({ nodeType: "n8n-nodes-base.slack" })

🛠️ Development

Commands

# Build & Test
npm run build          # Build TypeScript
npm run rebuild        # Rebuild node database
npm run test-nodes     # Test critical nodes
npm run validate       # Validate node data
npm test               # Run all tests
npm run typecheck      # Check TypeScript types

# Update Dependencies
npm run update:n8n:check  # Check for n8n updates
npm run update:n8n        # Update n8n packages

# Run Server
npm start              # Start in stdio mode
npm run start:http     # Start in HTTP mode
npm run dev            # Development with auto-reload
npm run dev:http       # HTTP dev mode

# Docker
docker compose up -d   # Start with Docker
docker compose logs    # View logs
docker compose down    # Stop containers

Automated Updates

n8n releases weekly. This project includes automated dependency updates:

• GitHub Actions: Runs weekly to check and update n8n packages
• Update Script: npm run update:n8n for manual updates
• Validation: All updates are tested before merging

See Dependency Updates Guide for details.

Project Structure

n8n-mcp/
├── src/
│   ├── loaders/       # NPM package loaders
│   ├── parsers/       # Node metadata extraction
│   ├── mappers/       # Documentation mapping
│   ├── database/      # SQLite with FTS5
│   ├── scripts/       # Build and maintenance
│   ├── mcp/           # MCP server implementation
│   └── utils/         # Shared utilities
├── data/              # SQLite database
├── docs/              # Documentation
└── docker-compose.yml # Docker configuration

📊 Metrics & Coverage

Current database coverage (updated to n8n v1.97.1):

• ✅ 525/525 nodes loaded (100%)
• ✅ 520 nodes with properties (99%)
• ✅ 334 nodes with operations (63.6%)
• ✅ 457 nodes with documentation (87%)
• ✅ 263 AI-capable tools detected
• ✅ All critical nodes validated

📚 Documentation

• Installation Guide - Detailed setup instructions
• Claude Desktop Setup - Configure Claude Desktop
• HTTP Deployment Guide - Remote server deployment
• Docker Guide - Container deployment
• Troubleshooting - Common issues and solutions
• Architecture - Technical design details

🔄 Recent Updates

v2.3.3 - Automated Dependency Updates

• ✅ Implemented automated n8n dependency update system
• ✅ Created GitHub Actions workflow for weekly updates
• ✅ Successfully updated to n8n v1.97.1
• ✅ Fixed validation script for new node type format
• ✅ Significant increase in AI-capable nodes (35 → 263)

v2.3.2 - HTTP Server Fix

• ✅ Fixed "stream is not readable" error
• ✅ Direct JSON-RPC implementation bypassing transport issues
• ✅ Added USE_FIXED_HTTP=true for stable HTTP mode
• ✅ Average response time: ~12ms

v2.3.0 - Universal Compatibility

• ✅ Automatic database adapter fallback
• ✅ Works with ANY Node.js version
• ✅ No manual configuration needed

See CHANGELOG.md for full version history.

📦 License

This project uses the Sustainable Use License. Key points:

• ✅ Free for internal business and personal use
• ✅ Modifications allowed for own use
• ❌ Cannot host as a service without permission
• ❌ Cannot include in commercial products without permission

See LICENSE for full details.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run tests (npm test)
4. Submit a pull request

👏 Acknowledgments

• n8n team for the workflow automation platform
• Anthropic for the Model Context Protocol
• All contributors and users of this project