n8n-mcp-connector
Provides tools for managing and executing N8N workflows, including creating, updating, and deleting nodes and connections, activating/deactivating workflows, monitoring execution status, and managing webhooks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@n8n-mcp-connector execute my 'Daily Report' workflow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
N8N MCP Connector v2.0.0
A high-performance Model Context Protocol (MCP) server that provides seamless integration with N8N automation platform. This connector enables AI assistants and other MCP clients to interact with N8N workflows, executions, and automation capabilities with enterprise-grade reliability and performance.
✨ Features
Core Capabilities
Workflow Management: Execute, list, and manage N8N workflows with advanced filtering
Execution Monitoring: Real-time tracking of workflow execution status and results
Advanced Operations: Create nodes, manage connections, and configure webhooks
Node Management: Full CRUD operations for individual workflow nodes
Performance & Reliability
Intelligent Caching: Multi-tier caching system with TTL and LRU eviction
Connection Pooling: Optimized HTTP connections for better performance
Circuit Breaker: Resilience patterns for external API failures
Metrics & Monitoring: Comprehensive performance tracking and health checks
Rate Limiting: Built-in protection against API abuse
Developer Experience
Type Safety: Full TypeScript implementation with strict typing
Modular Architecture: Clean, maintainable, and extensible codebase
Comprehensive Testing: Unit, integration, and E2E test coverage
Rich Documentation: Detailed guides and API documentation
Configuration Management: Centralized, validated configuration system
Related MCP server: MCP Server for n8n Integration
🚀 Quick Start
Prerequisites
Active n8n instance
API access configured in n8n
Claude Desktop installed
📦 Instalación Remota (Recomendado)
Nuestros scripts de instalación ahora detectan automáticamente el mejor ejecutor de paquetes (uvx, npx, npm) disponible en tu sistema para una experiencia más fluida y un rendimiento óptimo.
Puedes anular el ejecutor detectado configurando la variable de entorno RUNNER. Por ejemplo: RUNNER=npm ./install-remote.sh.
Opción A: Ejecución Remota con Runner Dinámico
# Instalación automática
curl -fsSL https://raw.githubusercontent.com/carlosjperez/n8n-mcp-connector/main/install-remote.sh | bash
# Selecciona la opción 1Opción B: MCP.so
# Instalación automática
curl -fsSL https://raw.githubusercontent.com/carlosjperez/n8n-mcp-connector/main/install-remote.sh | bash
# Selecciona opción 2 (MCP.so)🔧 Instalación Local (Desarrollo)
# Clone repository
git clone https://github.com/carlosjperez/n8n-mcp-connector.git
cd n8n-mcp-connector
# Install dependencies
npm install
# Configure environment
cp .env.example .env
# Edit .env with your n8n credentials
# Build and start
npm run build
npm startEnvironment Configuration
# Required: n8n instance URL
N8N_BASE_URL=http://localhost:5678
# Option 1: API Key authentication (recommended)
N8N_API_KEY=your_api_key_here
# Option 2: Username/Password authentication
N8N_USERNAME=your_username
N8N_PASSWORD=your_passwordClaude Desktop Integration
Nota: Los scripts de instalación se encargan de esto automáticamente. La siguiente configuración es un ejemplo. El campo command será rellenado por el script de instalación con el ejecutor de paquetes detectado (uvx, npx, o npm).
📦 Configuración de Ejecución Remota (Ejemplo)
{
"mcpServers": {
"n8n-workflows": {
"command": "npx",
"args": ["n8n-mcp-connector"],
"env": {
"N8N_BASE_URL": "https://tu-instancia-n8n.com",
"N8N_API_KEY": "tu_api_key_aqui"
}
}
}
}☁️ Configuración MCP.so (Totalmente remoto)
{
"mcpServers": {
"n8n-workflows": {
"command": "mcp",
"args": ["install", "n8n-workflows/carlosjperez"],
"env": {
"N8N_BASE_URL": "https://tu-instancia-n8n.com",
"N8N_API_KEY": "tu_api_key_aqui"
}
}
}
}🔧 Configuración Local (Desarrollo)
{
"mcpServers": {
"n8n-automation": {
"command": "node",
"args": ["./dist/index.js"],
"cwd": "/absolute/path/to/n8n-mcp-connector",
"env": {
"N8N_BASE_URL": "http://localhost:5678",
"N8N_API_KEY": "your_api_key_here"
}
}
}
}🛠️ Available Tools
The MCP server provides comprehensive tools for N8N automation:
Core Workflow Tools
execute_workflow: Execute workflows with advanced options and monitoringlist_workflows: List workflows with filtering, pagination, and cachingget_workflow: Get detailed workflow information with intelligent cachingget_execution_status: Real-time execution status with performance metricslist_executions: List executions with filtering and statisticsactivate_workflow: Activate/deactivate workflows with validationcreate_webhook: Create webhook endpoints with security options
Advanced Node Management
create_node: Create new nodes with validation and type checkingupdate_node: Update existing nodes with conflict detectiondelete_node: Safely remove nodes with dependency checkingcreate_connection: Create connections with validationdelete_connection: Remove connections with impact analysis
Monitoring & Diagnostics
Built-in health checks and status monitoring
Performance metrics and cache statistics
Error tracking and debugging tools
Connection pool and resource monitoring
🧪 Testing
Comprehensive testing strategy with multiple test types:
# Run all tests
npm test
# Run specific test suites
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:e2e # End-to-end tests
# Run with coverage
npm run test:coverage
# Run in watch mode
npm run test:watch
# Performance testing
npm run test:performance🔧 Development
# Start development server with hot reload
npm run dev
# Development with debug logging
DEBUG=n8n-mcp:* npm run dev
# Code quality
npm run lint # ESLint
npm run format # Prettier
npm run type-check # TypeScript
# Build optimization
npm run build:analyze # Bundle analysis
npm run build:production # Optimized build🏗️ Architecture
The connector follows a modern, scalable architecture with performance optimizations:
src/
├── config/ # Centralized configuration management
│ └── index.ts # Validated configuration with defaults
├── clients/ # External service clients
│ └── n8n-client.ts # N8N API client with caching & pooling
├── handlers/ # MCP tool handlers
│ ├── tool-handlers.ts
│ └── advanced-tool-handlers.ts
├── utils/ # Utility modules
│ ├── cache.ts # Intelligent caching system
│ ├── metrics.ts # Metrics and monitoring
│ ├── logger.ts # Structured logging
│ ├── validator.ts # Input validation
│ └── resilience.ts # Circuit breaker & retry logic
└── index.ts # Main server with monitoringKey Design Patterns
Singleton Pattern: Configuration and client instances
Factory Pattern: Tool handler creation
Observer Pattern: Event-driven metrics collection
Circuit Breaker: Resilience for external API calls
Cache-Aside: Intelligent caching with TTL and LRU eviction
Performance Features
Multi-tier Caching: Different TTL for different data types
Connection Pooling: Optimized HTTP connections
Request Batching: Efficient API usage
Lazy Loading: On-demand resource initialization
Memory Management: Automatic cleanup and optimization
📊 Performance Metrics
Expected Performance
Request Latency: < 100ms (cached), < 500ms (uncached)
Throughput: > 1000 requests/minute
Cache Hit Ratio: > 80% for repeated requests
Memory Usage: < 512MB under normal load
Uptime: > 99.9% availability
Monitoring
# Health check
curl http://localhost:3000/health
# Detailed metrics
curl http://localhost:3000/metrics
# Cache statistics
curl http://localhost:3000/health/detailed📚 Documentation
Technical Guide - Comprehensive development guide
Architecture Documentation - System architecture details
API Reference - Complete API documentation
Deployment Guide - Production deployment instructions
Troubleshooting - Common issues and solutions
⚙️ Configuration
The connector uses a hierarchical configuration system with environment variables. Copy .env.example to .env and configure:
Required Settings
N8N_BASE_URL: Your N8N instance URL (e.g.,http://localhost:5678)N8N_API_KEY: Your N8N API key (get from N8N Settings > API Keys)
Performance Settings
# Cache Configuration
CACHE_DEFAULT_TTL=600000 # 10 minutes default TTL
CACHE_WORKFLOWS_DETAILS_TTL=600000 # Workflow details cache
CACHE_EXECUTIONS_COMPLETED_TTL=1800000 # Completed executions cache
# Connection Settings
CONNECTION_POOL_SIZE=10 # HTTP connection pool size
REQUEST_TIMEOUT=30000 # Request timeout
CIRCUIT_BREAKER_THRESHOLD=5 # Circuit breaker threshold
# Monitoring
MONITORING_ENABLED=true # Enable metrics collection
METRICS_INTERVAL=30000 # Metrics collection intervalEnvironment-Specific Settings
# Development
NODE_ENV=development
LOG_LEVEL=debug
DEBUG=n8n-mcp:*
# Production
NODE_ENV=production
LOG_LEVEL=warn
MONITORING_ENABLED=true🔒 Security
Environment-based credential management
Input validation and sanitization
Rate limiting and timeout protection
Error isolation without information leakage
📚 Usage Examples
Basic Workflow Execution
Ask Claude: "Execute the data-processing workflow with customer ID 12345"Monitoring Active Workflows
Ask Claude: "Show me all running workflows and their current status"Webhook Creation
Ask Claude: "Create a webhook for the order-processing workflow"🤝 Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🤖 Sistema de Automatización
¡NUEVO! Sistema automatizado de gestión de errores CI/CD con integración Linear:
✅ Detección automática de fallos en CI/CD
🎯 Asignación inteligente de agentes especializados
📊 Sincronización GitHub ↔ Linear
📈 Métricas y seguimiento automatizado
🚀 Configuración Rápida
# Configuración automática del sistema
./setup-automation-system.sh
# Verificar funcionamiento
./verify-automation-system.sh📖 Documentación completa: README-AUTOMATION.md
🆘 Support
🛣 Roadmap
Advanced workflow templates
Bulk operations support
Real-time monitoring dashboard
Integration with additional automation platforms
Enhanced error reporting and analytics
Available Tools
12 toolsactivate_workflowC
Activate or deactivate a workflow with validation and confirmation
Inputs: active (required), workflowId (required).
create_connectionC
Create a connection between two nodes in a workflow
Inputs: connection (required), workflowId (required).
create_nodeC
Create a new node in a workflow with advanced configuration options
Inputs: node (required), workflowId (required), position, autoConnect, +1 more.
create_webhookC
Create a webhook URL for a workflow with custom configuration
Inputs: workflowId (required), path, method.
delete_connectionC
Delete a connection between two nodes in a workflow
Inputs: workflowId (required), sourceNodeId (required), targetNodeId (required), targetInputIndex, +1 more.
delete_nodeC
Delete a node from a workflow
Inputs: nodeId (required), workflowId (required), cascadeDelete.
execute_workflowC
Execute an n8n workflow by ID or name with advanced options and monitoring
Inputs: workflowId (required), data, waitForCompletion.
get_execution_statusB
Get the status and details of a workflow execution with performance metrics
Inputs: executionId (required).
get_workflowB
Get detailed information about a specific workflow including nodes and connections
Inputs: workflowId (required).
list_executionsB
List recent workflow executions with filtering, pagination, and statistics
Inputs: limit, offset, status, workflowId.
list_workflowsC
List all available workflows with filtering and pagination
Inputs: tags, limit, active, offset.
update_nodeC
Update an existing node in a workflow
Inputs: nodeId (required), updates (required), workflowId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target clearly distinct resources and actions: nodes, connections, workflows, and executions. create_webhook slightly overlaps with create_node since a webhook is a node type in n8n, but the descriptions clarify the specialized intent.
All tools use a consistent snake_case verb_noun pattern such as create_node, update_node, list_workflows, and execute_workflow. Minor plural/singular variations are conventional and readable.
12 tools is well within a reasonable range for an n8n connector, covering key node, connection, workflow, and execution operations without obvious bloat. Each tool appears to earn its place.
Core node and connection operations are present, but the workflow lifecycle is incomplete: there is no create_workflow, update_workflow, or delete_workflow, and no update_connection. These gaps may force agents to work around missing fundamental workflow management operations.
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Open-source Zapier/n8n alternative as an MCP server: agents build, run and debug your workflows.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants to interact with n8n workflows through natural language, supporting actions like listing, creating, updating, executing and monitoring workflows.246 npm1,631MIT
- FlicenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol server that enables AI agents to interact with n8n workflows and automation tools through a standardized interface, allowing execution of workflows and access to n8n functions.-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows AI agents to interact with n8n workflows through natural language, enabling workflow management and execution via SSE connections.7MIT
- AlicenseAqualityAmaintenanceA Model Context Protocol server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations for effective workflow automation.2947,555 npm23,286MIT