MCP-SERVER-N8N

asafalfa/MCP-SERVER-N8N

3.2

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

The N8N MCP Server is a Model Context Protocol server designed to facilitate interaction with N8N workflows and executions programmatically through Cursor IDE.

Tools
4
Resources
0
Prompts
0

N8N MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with N8N workflows and executions. This server allows you to create, manage, and execute N8N workflows programmatically through Cursor IDE.

🚀 Features

  • 🔗 Connection Management: Test and verify N8N server connectivity
  • 📋 Workflow Management: Create, read, update, delete workflows
  • ⚡ Workflow Execution: Execute workflows with custom data
  • 🎯 Advanced Node Creation: Create workflows with all possible N8N nodes
  • 💻 Custom Code Support: Add custom JavaScript, HTML, and function code to any node
  • 🔄 Workflow Lifecycle: Activate, deactivate, and manage workflow states
  • 📊 Execution Tracking: Monitor workflow executions and results
  • 🐳 Containerized: Ready-to-use Docker container
  • 🔧 Cross-Platform: Works on Windows, macOS, and Linux

🛠️ Available Tools

🔗 Connection & Basic Operations

  • n8n_test_connection - Test connection to N8N server
  • n8n_get_workflows - Get all workflows from N8N
  • n8n_get_workflow - Get a specific workflow by ID

📝 Workflow Creation

  • n8n_create_workflow - Create a basic workflow
  • n8n_create_advanced_workflow - Create workflow with custom nodes and code
  • n8n_get_available_nodes - Get list of available node types and templates

🎯 Node Management

  • n8n_create_node_with_code - Create a node with custom code

🔄 Workflow Lifecycle

  • n8n_update_workflow - Update an existing workflow
  • n8n_delete_workflow - Delete a workflow
  • n8n_activate_workflow - Activate a workflow
  • n8n_deactivate_workflow - Deactivate a workflow

⚡ Execution & Monitoring

  • n8n_execute_workflow - Execute a workflow with custom data
  • n8n_get_workflow_executions - Get workflow executions

🎯 Supported Node Types

The MCP server supports creating workflows with the following node types:

🔧 Core Nodes

  • manualTrigger - Manual workflow trigger
  • code - JavaScript code execution
  • function - Function node for data processing
  • httpRequest - HTTP API calls
  • webhook - Webhook endpoints

📊 Data Processing

  • set - Set data values
  • merge - Merge multiple data streams
  • splitInBatches - Split data into batches
  • if - Conditional logic
  • switch - Multi-path routing

📤 Output Nodes

  • html - Generate HTML output
  • markdown - Generate Markdown output
  • email - Send emails
  • fileOperations - File operations

🔗 Integration Nodes

  • googleSheets - Google Sheets integration
  • slack - Slack messaging
  • discord - Discord messaging
  • telegram - Telegram messaging

⏰ Automation Nodes

  • cron - Scheduled triggers

🚀 Quick Start

Prerequisites

  • Docker and Docker Compose installed
  • N8N instance running and accessible
  • N8N API key generated

Step 1: Clone and Setup

# Clone the repository
git clone <repository-url>
cd n8n-mcp-server

# Run setup script
./setup.sh  # Linux/Mac
# OR
setup.bat   # Windows

Step 2: Configure Environment

Edit the .env file with your N8N configuration:

# N8N Configuration
N8N_BASE_URL=http://your-n8n-instance:5678
N8N_API_KEY=your-n8n-api-key-here
N8N_USERNAME=  # Optional
N8N_PASSWORD=  # Optional

Step 3: Deploy

# Start the container
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs n8n-mcp-server

Step 4: Configure Cursor

Add to your Cursor MCP configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "n8n-mcp-server"],
      "env": {
        "N8N_BASE_URL": "http://your-n8n-instance:5678",
        "N8N_API_KEY": "your-n8n-api-key-here"
      }
    }
  }
}

📖 Usage Examples

🔗 Test Connection

# Test if N8N server is accessible
result = await n8n_test_connection()
print(result)

📋 Get Available Nodes

# Get all available node types
nodes = await n8n_get_available_nodes()
print(nodes)

🎯 Create Node with Custom Code

# Create a Code node with custom JavaScript
node_data = await n8n_create_node_with_code(
    node_type="code",
    node_name="Data Processor",
    custom_code="""
    return items.map(item => ({
        json: {
            ...item.json,
            processed: true,
            timestamp: new Date().toISOString()
        }
    }));
    """
)

📝 Create Advanced Workflow

# Create a complex workflow with multiple nodes
workflow_config = {
    "name": "Data Processing Pipeline",
    "nodes_config": [
        {
            "type": "manualTrigger",
            "name": "Start",
            "position": [240, 300]
        },
        {
            "type": "code",
            "name": "Data Generator",
            "code": """
            return [
                { json: { id: 1, name: "Alice", age: 30 } },
                { json: { id: 2, name: "Bob", age: 25 } }
            ];
            """,
            "position": [460, 300]
        },
        {
            "type": "function",
            "name": "Process Data",
            "code": """
            for (const item of items) {
                item.json.processed = true;
                item.json.timestamp = new Date().toISOString();
            }
            return items;
            """,
            "position": [680, 300]
        },
        {
            "type": "html",
            "name": "HTML Output",
            "code": """
            <html>
            <head><title>Processed Data</title></head>
            <body>
                <h1>Results</h1>
                <ul>
                {{#each $json}}
                    <li>{{name}} ({{age}}) - {{#if processed}}Processed{{else}}Pending{{/if}}</li>
                {{/each}}
                </ul>
            </body>
            </html>
            """,
            "position": [900, 300]
        }
    ]
}

result = await n8n_create_advanced_workflow(
    name=workflow_config["name"],
    nodes_config=json.dumps(workflow_config["nodes_config"])
)

⚡ Execute Workflow

# Execute a workflow with custom data
execution_data = {
    "input": "test data",
    "timestamp": "2024-01-01T00:00:00Z"
}

result = await n8n_execute_workflow(
    workflow_id="your-workflow-id",
    data=json.dumps(execution_data)
)

🔄 Manage Workflow Lifecycle

# Activate a workflow
await n8n_activate_workflow(workflow_id="your-workflow-id")

# Execute the workflow
await n8n_execute_workflow(workflow_id="your-workflow-id")

# Get execution history
executions = await n8n_get_workflow_executions(
    workflow_id="your-workflow-id",
    limit=10
)

# Deactivate the workflow
await n8n_deactivate_workflow(workflow_id="your-workflow-id")

🎨 Node Code Examples

JavaScript Code Node

// Generate data
return [
    { json: { id: 1, name: "Alice", age: 30 } },
    { json: { id: 2, name: "Bob", age: 25 } },
    { json: { id: 3, name: "Charlie", age: 35 } }
];

// Process incoming data
for (const item of items) {
    item.json.processed = true;
    item.json.timestamp = new Date().toISOString();
    item.json.fullName = `${item.json.firstName} ${item.json.lastName}`;
}
return items;

// API response processing
const results = [];
for (const item of items) {
    if (item.json.status === 'success') {
        results.push({
            json: {
                id: item.json.id,
                message: 'Processed successfully',
                data: item.json.data
            }
        });
    }
}
return results;

Function Node

// Data transformation
for (const item of items) {
    // Add computed fields
    item.json.fullName = `${item.json.firstName} ${item.json.lastName}`;
    item.json.age = new Date().getFullYear() - item.json.birthYear;
    
    // Add processing timestamp
    item.json.processedAt = new Date().toISOString();
    
    // Add status based on conditions
    if (item.json.age >= 18) {
        item.json.status = 'adult';
    } else {
        item.json.status = 'minor';
    }
}
return items;

// Data filtering
const filteredItems = items.filter(item => 
    item.json.status === 'active' && 
    item.json.score > 80
);

return filteredItems.map(item => ({
    json: {
        id: item.json.id,
        name: item.json.name,
        score: item.json.score,
        category: item.json.score > 90 ? 'excellent' : 'good'
    }
}));

HTML Node

<html>
<head>
    <title>Data Report</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .header { background: #f0f0f0; padding: 10px; border-radius: 5px; }
        .item { margin: 10px 0; padding: 10px; border: 1px solid #ddd; }
        .success { background: #d4edda; }
        .error { background: #f8d7da; }
    </style>
</head>
<body>
    <div class="header">
        <h1>Data Processing Report</h1>
        <p>Generated on: {{$now}}</p>
    </div>
    
    {{#each $json}}
    <div class="item {{#if processed}}success{{else}}error{{/if}}">
        <h3>{{name}}</h3>
        <p><strong>ID:</strong> {{id}}</p>
        <p><strong>Age:</strong> {{age}}</p>
        <p><strong>Status:</strong> {{#if processed}}Processed{{else}}Pending{{/if}}</p>
        {{#if timestamp}}
        <p><strong>Timestamp:</strong> {{timestamp}}</p>
        {{/if}}
    </div>
    {{/each}}
    
    <div class="header">
        <h2>Summary</h2>
        <p>Total items: {{$json.length}}</p>
        <p>Processed: {{#filter $json "processed" true}}{{/filter.length}}</p>
    </div>
</body>
</html>

HTTP Request Node

// URL: https://api.example.com/users
// Method: GET
// Headers: { "Authorization": "Bearer {{$json.token}}" }

// For POST requests with data
// URL: https://api.example.com/users
// Method: POST
// Body: { "name": "{{$json.name}}", "email": "{{$json.email}}" }

🔧 Development

Local Development

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export N8N_BASE_URL=http://localhost:5678
export N8N_API_KEY=your-api-key

# Run the server
python n8n_mcp_server_simple.py

Testing

# Run the test suite
python test_container.py

# Test specific functionality
python -c "
import asyncio
from n8n_mcp_server_simple import n8n_client
result = asyncio.run(n8n_client.test_connection())
print(result)
"

🔍 Troubleshooting

Common Issues

  1. Connection Failed

    • Verify N8N is running on the correct port
    • Check API key is valid
    • Ensure network connectivity

  2. Workflow Creation Fails

    • Verify node types are supported
    • Check JSON syntax in custom code
    • Ensure required parameters are provided

  3. Execution Errors

    • Check workflow is activated
    • Verify input data format
    • Review execution logs

Debug Mode

Enable debug logging by setting environment variables:

export DEBUG=1
export PYTHONUNBUFFERED=1

Logs

# View container logs
docker-compose logs n8n-mcp-server

# Follow logs in real-time
docker-compose logs -f n8n-mcp-server

# View specific log levels
docker-compose logs n8n-mcp-server | grep ERROR

🔒 Security

Best Practices

  1. Environment Variables: Never hardcode secrets
  2. API Keys: Rotate keys regularly
  3. Network Security: Use proper network isolation
  4. Container Security: Run with minimal privileges

Production Deployment

For production environments, use secrets management:

# Use Docker secrets
docker run -d --name n8n-mcp-server \
  --secret n8n_api_key \
  -e N8N_API_KEY_FILE=/run/secrets/n8n_api_key \
  n8n-mcp-server

📊 Monitoring

Health Checks

The container includes health check endpoints:

# Check container health
docker inspect n8n-mcp-server | grep Health -A 10

Metrics

Monitor workflow executions and performance:

# Get execution metrics
executions = await n8n_get_workflow_executions(
    workflow_id="your-workflow-id",
    limit=100
)

# Analyze execution data
for execution in executions['data']:
    print(f"Execution {execution['id']}: {execution['status']}")

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

📄 License

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

🆘 Support

For issues and questions:

  • Check the troubleshooting section
  • Review N8N documentation for API details
  • Create an issue on GitHub

📚 Additional Resources