n8n MCP Server

A comprehensive Model Context Protocol (MCP) server for n8n workflow automation. This server enables AI assistants to fully manage n8n workflows, monitor executions, and access a complete node knowledge base through the MCP protocol.

🚀 Features

✅ Complete Workflow Management

• Create & Update - Build workflows programmatically with full node configuration
• Activate & Deactivate - Control workflow execution state
• Delete - Clean up workflows when no longer needed
• List & Filter - Find workflows by status, tags, name, or project
• Smart Updates - Partial or complete workflow updates with automatic merging

✅ Execution Monitoring & Control

• List Executions - Query execution history with filtering and pagination
• Execution Details - Get detailed execution information with duration analysis
• Retry Failed Executions - Automatically retry with optional workflow reload
• Delete Executions - Clean up execution history
• Statistics - Automatic success rate and status distribution calculation

✅ Enhanced Node Knowledge Base (456 nodes)

• Complete n8n node catalog with parameter examples from real workflows
• Usage Statistics - See which nodes are most commonly used
• Parameter Examples - Real-world parameter configurations
• Smart Search - Find nodes by name, category, or functionality
• AI Agent Support - Full support for AI/LangChain nodes

✅ Production Ready

• TypeScript - Full type safety and modern development experience
• Comprehensive Error Handling - Clear error messages and logging
• API Validation - All methods verified against n8n API v1.1.1
• Extensive Testing - Test suites for all major features
• CLI Support - Works with npx or global installation

🛠️ Available Tools (20+)

Workflow Management

• n8n_list_workflows - List and filter workflows
• n8n_get_workflow - Get workflow details
• n8n_create_workflow - Create new workflows
• n8n_update_workflow - Update existing workflows
• n8n_activate_workflow - Activate workflows
• n8n_deactivate_workflow - Deactivate workflows
• n8n_delete_workflow - Delete workflows

Execution Management

• n8n_list_executions - Query execution history
• n8n_get_execution - Get execution details
• n8n_retry_execution - Retry failed executions
• n8n_delete_execution - Delete execution records

Node Discovery

• search_n8n_nodes - Search nodes by name or category
• get_n8n_node_details - Get detailed node information with usage examples
• list_n8n_categories - Browse all node categories
• get_popular_n8n_nodes - Discover most commonly used nodes (based on real usage)
• get_n8n_tool_nodes - Find AI-compatible nodes
• get_n8n_stats - Get comprehensive node statistics

System Tools

• echo - Test MCP connectivity
• n8n_health_check - Verify n8n instance connectivity

📚 Available Resources

• n8n://server-info - Server and connection information
• n8n://nodes/search - Node search with query parameters
• n8n://nodes/{nodeName} - Specific node details
• n8n://categories - All node categories
• n8n://categories/{category} - Nodes in specific category
• n8n://stats - Node knowledge base statistics
• n8n://nodes/popular - Popular node list (based on real usage)
• n8n://nodes/tools - AI-compatible nodes

📊 Data Sources

• Node Definitions: 456 nodes from n8n source code
• Parameter Examples: Real configurations from 57 production workflows
• Usage Statistics: Actual usage data showing most popular nodes
• Node Schemas: Complete parameter schemas for validation

Top 5 most used nodes:

1. set (36 uses) - Data manipulation
2. agent (23 uses) - AI Agent
3. respondToWebhook (23 uses) - Webhook responses
4. webhook (19 uses) - Webhook triggers
5. lmChatOllama (16 uses) - Ollama LLM

Installation

Global Installation

npm install -g n8n-mcp-server

Using npx

npx n8n-mcp-server --n8n-url http://localhost:5678 --api-key your-api-key

Configuration

The server can be configured using environment variables or command line arguments:

Environment Variables

export N8N_URL=http://localhost:5678
export N8N_API_KEY=your-api-key

Command Line Arguments

n8n-mcp-server --n8n-url http://localhost:5678 --api-key your-api-key

Usage

MCP Client Configuration

Add to your MCP client configuration (e.g., Kiro IDE):

{
  "mcpServers": {
    "n8n-mcp-server": {
      "command": "npx",
      "args": ["@myflowsjs/n8n-mcp-server"],
      "env": {
        "N8N_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Example Usage

Once configured, you can use the tools in your AI assistant:

Node Discovery

// Search for HTTP-related nodes
search_n8n_nodes({ query: "http", limit: 5 })

// Get details about a specific node with usage examples
get_n8n_node_details({ nodeName: "set" })

// Get most popular nodes based on real usage
get_popular_n8n_nodes({ limit: 10 })

Workflow Management

// List all workflows
n8n_list_workflows({ limit: 10 })

// Create a new workflow
n8n_create_workflow({
  name: "My Workflow",
  nodes: [...],
  connections: {...}
})

// Update a workflow
n8n_update_workflow({
  id: "workflow-id",
  name: "Updated Name"
})

// Activate a workflow
n8n_activate_workflow({ id: "workflow-id" })

// Delete a workflow
n8n_delete_workflow({ id: "workflow-id" })

Execution Monitoring

// List recent executions
n8n_list_executions({ limit: 20 })

// Filter by status
n8n_list_executions({ status: "error", limit: 10 })

// Get execution details
n8n_get_execution({ id: 12345 })

// Retry a failed execution
n8n_retry_execution({ id: 12345, loadWorkflow: true })

// Delete an execution
n8n_delete_execution({ id: 12345 })

# Check server statistics
get_n8n_stats()

Resource Access

You can also access information via resources:

• Browse categories: n8n://categories
• Search nodes: n8n://nodes/search?q=email&category=Communication
• Get node details: n8n://nodes/httpRequest
• View statistics: n8n://stats

📦 Data Files

This package includes pre-extracted data files that are bundled with the published package:

Included Data

• Node Information (nodes.json) - 529 nodes with descriptions, categories, and metadata
• Parameter Examples (node-parameter-examples.json) - Real-world parameter usage from 57 workflows

No External Dependencies

• ✅ All data is pre-extracted and included in the package
• ✅ No need for n8n source code
• ✅ No need to run extraction scripts
• ✅ Fast startup with internal data storage

For Developers

If you want to update the data files, see DATA-EXTRACTION.md for details on:

• How to extract node parameter examples from your n8n instance
• How to update node information
• Data file formats and update strategies

Development

Prerequisites

• Node.js 18+
• npm or yarn
• Access to an n8n instance with API enabled

Setup

# Clone the repository
git clone https://github.com/myflows-platform/n8n-mcp-server-v2.git
cd n8n-mcp-server-v2/n8n-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start in development mode
npm run dev

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run dev: Watch mode for development
• npm run start: Start the compiled server
• npm run lint: Run ESLint
• npm run lint:fix: Fix ESLint issues automatically
• npm run clean: Remove build artifacts

Testing

To test the MCP server functionality:

# Build the project
npm run build

# Run the MCP test script
node test-mcp.js

The test script verifies:

• MCP protocol initialization
• Tool listing and execution
• Resource listing and reading
• Error handling
• n8n connectivity checking

See test-results.md for detailed test results.

License

MIT