n8n MCP Server (Custom)

A lightweight MCP server for n8n API following the Hybrid MCP Light Blueprint pattern.

Design Philosophy

This server implements the "Hybrid MCP Light" pattern:

1. 5 Curated Tools - Most frequently used operations as dedicated tools
2. API Pass-through - Raw API access for complete coverage
3. Embedded Documentation - API reference as an MCP resource

This approach provides a clean tool surface for AI agents while ensuring 100% API capability coverage.

Curated Tools

Tool	Description
list_workflows	List all workflows with pagination
get_workflow	Get complete workflow by ID
list_executions	List execution history with filters
get_execution	Get execution details with optional data
trigger_webhook	Trigger workflow via webhook
n8n_api_call	Raw API pass-through for any operation

Configuration

Variable	Required	Description
N8N_URL	Yes	n8n instance URL (without trailing slash)
N8N_API_KEY	Yes	API key from n8n Settings > API
PORT	No	Server port (default: 8000)

Quick Start

Docker (Recommended)

docker run -d \
  -e N8N_URL=https://n8n.example.com \
  -e N8N_API_KEY=your-api-key \
  -p 8000:8000 \
  gitea.ext.ben.io/b3nw/n8n-mcp-custom:latest

Docker Compose

cp .env.example .env
# Edit .env with your n8n credentials
docker-compose up -d

Local Development

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Copy and configure environment
cp .env.example .env
# Edit .env with your credentials

# Run server
python server.py

MCP Client Configuration

Configure your MCP client to connect to:

http://localhost:8000/mcp

For streamable HTTP transport (recommended):

{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

API Reference

The server exposes an API reference resource at n8n://api-reference which documents all available n8n API endpoints for use with the n8n_api_call tool.

Common Operations via API Pass-through

# Create a workflow
n8n_api_call('/workflows', 'POST', body='{"name": "My Workflow", "nodes": [...], "connections": {...}}')

# Activate a workflow
n8n_api_call('/workflows/123/activate', 'POST')

# List credentials
n8n_api_call('/credentials')

# Create a tag
n8n_api_call('/tags', 'POST', body='{"name": "production"}')

# Delete an execution
n8n_api_call('/executions/456', 'DELETE')

Health Check

The server provides a health check endpoint at /health that verifies:

• Server is running
• n8n instance is accessible

curl http://localhost:8000/health

Architecture

n8n-mcp-custom/
├── server.py          # Main MCP server with tools and API client
├── pyproject.toml     # Python dependencies
├── Dockerfile         # Container build
├── docker-compose.yml # Local orchestration
├── .env.example       # Configuration template
└── README.md          # This file

License

MIT