n8n Unified MCP Server
anshwysmcbel2710/n8n-unified-mcp-server
Gateway MCP de automação n8n para assistentes de IA com 30 ferramentas integradas
Ver no GitHubServidor MCP de nível produção que conecta assistentes de IA (Claude, Gemini, Groq) a instâncias n8n via gateway único de alto desempenho. Expõe 30 ferramentas organizadas em orquestração de workflows, execução, validação e inteligência, com autenticação, cache inteligente e suporte multi-transporte (SSE/STDIO).
Instalação
npx convez-ai anshwysmcbel2710/n8n-unified-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Conectar Claude, Gemini e outros assistentes de IA a workflows n8n
- Orquestração determinística de automações com agentes LLM
- Validação e deploy automático de workflows via assistentes de código
- Integração segura de credenciais e execução de workflows em escala
Veredito

Ferramenta sólida e bem-arquitetada para integração n8n com ecossistema MCP. Requer expertise em infraestrutura e já assume familiaridade com n8n + MCP; ideal para equipes construindo plataformas de automação agnósticas a assistentes de IA.
README
A tradução para o português deste README ainda está na fila.
🏷️ n8n Unified MCP Server
A production-grade, unified MCP server connecting every major AI coding assistant to your n8n instance via a single, high-performance gateway — 30 tools, zero friction.
🚀 Quick Start · 📖 API Docs · 🧱 Architecture · ☁️ Deploy
🧾 Executive Summary
The n8n Unified MCP Server is a production-ready, single-entry-point automation gateway that bridges every major AI coding assistant — Gemini CLI, Claude Code CLI, Groq CLI, Codex CLI, Antigravity IDE, and any MCP-compatible client — to a live n8n workflow automation instance. It exposes 30 carefully designed MCP tools organized into six functional categories: Workflow Management, Execution & Debugging, Node Documentation, Validation & Building, AI Intelligence, and Credentials.
The server is built on FastAPI + FastMCP using the MCP 2025-06-18 Streamable HTTP transport specification. It operates in dual-transport mode: HTTP/SSE for IDE and web clients, and stdio for CLI-based AI agents. An async, in-memory TTL cache with optional Redis backend keeps latency sub-100 ms. Bearer token authentication, structured JSON logging (structlog), Prometheus-compatible metrics, and a multi-stage Docker build ensure the system is secure, observable, and cloud-deployable from day one.
Enterprise-grade features include:
- 🔒 Stateless Bearer Token authentication on every MCP endpoint
- 🧠 Context-aware session memory tracking all tool calls and workflow state across an agent session
- ⚡ Intelligent TTL caching per resource type (workflows 30 s, nodes 1 h, executions 10 s)
- 🔁 Automatic retry with exponential backoff for transient n8n API failures (up to 3 attempts)
- 🛠️ Workflow validation and auto-fix pipeline before any deploy operation
- 📊 Prometheus metrics at
/metrics, health at/health, Swagger UI at/docs
📑 Table of Contents
🧩 Project Overview
The n8n Unified MCP Server solves a critical developer-experience problem: every AI coding assistant speaks a different dialect when trying to control n8n. Before this project, a developer using Gemini CLI would configure a different integration than one using Claude Code CLI, and none of them would share session context, caching, or validation logic.
This server acts as a unified protocol translator — it speaks MCP (Model Context Protocol) on the AI side and n8n REST API v1 on the automation side, providing a clean, authenticated, cached, and logged interface between them.
┌─────────────────────────────────────────────────────────────┐
│ AI AGENTS (Any MCP-Compatible Client) │
│ Gemini CLI │ Claude Code │ Groq CLI │ Codex │ IDE │
└──────────────────────────┬──────────────────────────────────┘
│ Bearer Token · MCP Protocol
▼
┌─────────────────────────────────────────────────────────────┐
│ n8n Unified MCP Server (port 8000) │
│ FastAPI + FastMCP │ 30 Tools │ Cache │ Auth │ Logs │
└──────────────────────────┬──────────────────────────────────┘
│ REST API v1 · X-N8N-API-KEY
▼
┌─────────────────────────────────────────────────────────────┐
│ n8n Instance (port 5678) │
│ Workflows · Executions · Nodes · Credentials │
└─────────────────────────────────────────────────────────────┘
What makes this project stand out:
- A single server replaces five different n8n integrations
- Session-level context memory allows AI agents to know what has already been done
- Validation and auto-fix prevent broken workflows from ever reaching n8n
- Full observability out of the box: structured logs, metrics, health checks
🎯 Objectives & Goals
| # | Objective | Priority | Outcome |
|---|---|---|---|
| 1 | Provide a single MCP endpoint for all AI clients | 🔴 Critical | One URL, one token, all clients |
| 2 | Expose all n8n REST API v1 capabilities as MCP tools | 🔴 Critical | 30 tools across 6 categories |
| 3 | Ensure zero data loss during workflow operations | 🔴 Critical | Validate → Auto-fix → Deploy pipeline |
| 4 | Enable context-aware AI assistance across tool calls | 🟡 High | Session context with 50-action history |
| 5 | Achieve sub-100 ms response for cached operations | 🟡 High | TTL cache with resource-specific windows |
| 6 | Support cloud-native deployment with zero cold starts | 🟡 High | Fly.io always-on + Docker multi-stage |
| 7 | Provide Prometheus-compatible observability | 🟢 Medium | /metrics, /health, structured logs |
| 8 | Allow optional Redis cache for horizontal scaling | 🟢 Medium | Redis URL config flag |
✅ Acceptance Criteria
| # | Criterion | Verification Method | Status |
|---|---|---|---|
| AC-01 | Server starts on port 8000 and responds at /health | curl http://localhost:8000/health returns {"status":"healthy"} | ✅ |
| AC-02 | All 30 MCP tools are registered and discoverable | MCP client tool list returns 30 entries | ✅ |
| AC-03 | Bearer token authentication rejects invalid tokens | Unauthenticated request returns HTTP 401 | ✅ |
| AC-04 | /health and /docs endpoints bypass authentication | Direct curl to /health without token returns 200 | ✅ |
| AC-05 | validate_workflow catches structural errors before deploy | Malformed JSON returns {"valid": false, "errors": [...]} | ✅ |
| AC-06 | auto_fix_workflow repairs missing IDs and positions | Fixed workflow passes validate_workflow with zero errors | ✅ |
| AC-07 | Cache returns hit on second identical request within TTL | /metrics shows incrementing cache_hits counter | ✅ |
| AC-08 | Session context persists across multiple tool calls | get_session_context reflects all prior actions in session | ✅ |
| AC-09 | n8n connectivity failure returns {"status": "degraded"} | Stopping n8n; /health degrades gracefully | ✅ |
| AC-10 | Docker image builds and runs without errors | docker build + docker run succeeds, /health responds | ✅ |
| AC-11 | Fly.io deployment is reachable at HTTPS endpoint | https://n8n-unified-mcp-server.fly.dev/health returns 200 | ✅ |
| AC-12 | Prometheus metrics are exposed in correct text format | curl /metrics returns valid Prometheus exposition format | ✅ |
💻 Prerequisites
System Requirements
| Component | Minimum | Recommended |
|---|---|---|
| Python | 3.11 | 3.12 |
| RAM | 256 MB | 512 MB+ |
| Disk | 200 MB | 500 MB |
| n8n Instance | v1.0+ | Latest stable |
| Docker (optional) | 24.x | Latest |
| Node.js (for npx tools) | 18.x | 20 LTS |
Required Accounts & Services
- Running n8n instance — local (
localhost:5678) or cloud (n8n Cloud, self-hosted) - n8n API Key — generated from n8n → Settings → API → Create API Key
- MCP Bearer Token — any secure random string you generate (min. 32 chars recommended)
Software Installation Checklist
- Python 3.12 installed and available as
pythonorpython3 -
pippackage manager available - n8n running and accessible (verify at
http://localhost:5678) - Docker installed (optional — for containerised deployment)
- Fly CLI installed (optional — for cloud deployment)
-
curlor Postman available for API testing
⚙️ Installation & Setup
Step 1 — Clone the Repository
git clone https://github.com/your-org/n8n-unified-mcp-server.git
cd n8n-unified-mcp-server
Step 2 — Create a Python Virtual Environment
python -m venv .venv
source .venv/bin/activate # macOS / Linux
.venv\Scripts\activate # Windows
Step 3 — Install Dependencies
pip install -r requirements.txt
Dependencies installed:
| Package | Purpose |
|---|---|
mcp | Model Context Protocol core runtime |
fastapi | ASGI web framework |
httpx | Async HTTP client for n8n API calls |
pydantic / pydantic-settings | Type-safe config & validation |
tenacity | Retry logic with exponential backoff |
structlog | Structured JSON logging |
python-jose | JWT / bearer token security |
passlib | Password / secret hashing utilities |
typing-extensions | Backported type hints |
Step 4 — Configure Environment Variables
Copy the example file and edit it:
cp .env.example .env
Minimum required configuration in .env:
N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your_n8n_api_key_here
MCP_BEARER_TOKEN=your_secure_random_token_here
Full environment variable reference:
| Variable | Required | Default | Description |
|---|---|---|---|
N8N_API_KEY | ✅ Yes | — | n8n REST API key from Settings → API |
N8N_BASE_URL | ✅ Yes | http://localhost:5678 | Base URL of your n8n instance |
MCP_BEARER_TOKEN | ⚠️ Strongly recommended | — | Shared secret for MCP client auth |
MCP_HOST | No | 0.0.0.0 | Server bind host |
MCP_PORT | No | 8000 | Server listen port |
LOG_LEVEL | No | INFO | DEBUG, INFO, WARNING, ERROR |
LOG_FORMAT | No | console | console (dev) or json (prod) |
CACHE_ENABLED | No | true | Toggle response caching |
CACHE_TTL_WORKFLOWS | No | 30 | Workflow list cache TTL in seconds |
CACHE_TTL_NODES | No | 3600 | Node docs cache TTL (1 hour) |
CACHE_TTL_EXECUTIONS | No | 10 | Execution cache TTL |
CACHE_TTL_TEMPLATES | No | 1800 | Template cache TTL (30 min) |
REDIS_URL | No | — | Optional Redis URL for multi-instance cache |
WORKERS | No | 4 | Uvicorn worker processes |
N8N_API_TIMEOUT | No | 30 | HTTP timeout for n8n calls (seconds) |
N8N_API_RETRIES | No | 3 | Retry attempts on transient failure |
N8N_MAX_CONNECTIONS | No | 20 | HTTP connection pool size |
ENABLE_WORKFLOW_VALIDATION | No | true | Enable pre-deploy validation |
ENABLE_AUTO_FIX | No | true | Enable auto-fix tool |
ENABLE_CONTEXT_MEMORY | No | true | Enable session context tracking |
ENABLE_TEMPLATE_SEARCH | No | true | Enable template search intelligence |
RATE_LIMIT_ENABLED | No | true | Enable rate limiting |
RATE_LIMIT_REQUESTS | No | 200 | Max requests per window |
RATE_LIMIT_WINDOW | No | 60 | Rate limit window in seconds |
Step 5 — Start the Server
HTTP/SSE mode (for IDE clients, Antigravity, Claude Desktop):
python main.py
stdio mode (for CLI agents — Claude Code CLI, Gemini CLI, Codex CLI):
python main.py --stdio
Using the startup scripts:
# Linux / macOS
chmod +x start.sh && ./start.sh
# Windows
start.bat
Step 6 — Verify the Server
curl http://localhost:8000/health
Expected response:
{
"status": "healthy",
"server": "n8n-unified-mcp-server",
"version": "1.0.0",
"n8n": { "n8n_reachable": true },
"cache": { "size": 0, "hits": 0, "misses": 0, "hit_rate_pct": 0.0 },
"active_sessions": 0
}
Step 7 — Connect an AI Client
Configure your AI client (see client-specific configs below):
Gemini CLI — ~/.gemini/settings.json:
{
"mcpServers": {
"n8n": {
"httpUrl": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_BEARER_TOKEN"
}
}
}
}
Claude Code CLI — claude_desktop_config.json:
{
"mcpServers": {
"n8n": {
"type": "http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_BEARER_TOKEN"
}
}
}
}
Groq CLI — ~/.groq/config.json:
{
"mcpServers": {
"n8n": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"http://localhost:8000/mcp",
"--header", "Authorization: Bearer YOUR_MCP_BEARER_TOKEN"
]
}
}
}
Codex CLI — ~/.codex/config.toml:
[mcp_servers.n8n]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:8000/mcp",
"--header", "Authorization: Bearer YOUR_MCP_BEARER_TOKEN"]
Antigravity IDE — mcp_config.json:
{
"mcpServers": {
"n8n": {
"serverUrl": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_BEARER_TOKEN",
"Content-Type": "application/json"
}
}
}
}
🔗 API Documentation
The server exposes a Swagger UI at http://localhost:8000/docs and ReDoc at http://localhost:8000/redoc.
REST Endpoints
| Method | Endpoint | Auth Required | Description |
|---|---|---|---|
GET | /health | ❌ No | Server + n8n connectivity check |
GET | /metrics | ❌ No | Prometheus-format cache & session metrics |
GET | /info | ❌ No | Server capabilities and feature flags |
POST | /mcp | ✅ Yes (Bearer) | MCP Streamable HTTP transport endpoint |
GET | /mcp/sse | ✅ Yes (Bearer) | MCP Server-Sent Events stream (IDE clients) |
POST | /cache/clear | ✅ Yes (Bearer) | Admin — flush all cached entries |
GET | /docs | ❌ No | Swagger UI |
GET | /redoc | ❌ No | ReDoc API docs |
MCP Protocol Interaction
All AI tool calls go through POST /mcp. The MCP protocol wraps each tool call in a JSON-RPC 2.0 envelope:
Request structure:
POST /mcp
Authorization: Bearer <token>
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_workflows",
"arguments": { "active_only": false, "limit": 50 }
}
}
Response structure:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{ \"total\": 12, \"workflows\": [...] }"
}
]
}
}
Response Headers (All Endpoints)
| Header | Description |
|---|---|
X-Request-ID | Unique request identifier for tracing |
X-Response-Time | Server processing time in milliseconds |
X-Server | Server name identifier |
🖥️ UI / Frontend
The n8n Unified MCP Server is a headless backend service — it has no user-facing frontend application. The UIs are the Swagger docs and the AI client interfaces.
Swagger UI (/docs)
- Location:
http://localhost:8000/docs - Framework: Auto-generated by FastAPI using OpenAPI 3.1
- Components: Interactive endpoint explorer, request/response schema browser, try-it-out console
- Authentication: Click the 🔒
Authorizebutton, enterBearer <your_token> - Styling: Default FastAPI Swagger theme; to customise, override the
swagger_ui_parametersin theFastAPI()constructor inmain.py
ReDoc (/redoc)
- Location:
http://localhost:8000/redoc - Purpose: Cleaner, read-only API reference documentation
- Styling: Can be customised via
redoc_urlandredoc_js_urlin FastAPI config
n8n Native UI
The n8n workflow editor UI remains at http://localhost:5678 and is fully independent. The MCP server interacts with n8n programmatically — it does not embed or proxy the n8n UI.
Changing Server Metadata (Displayed in Swagger)
To change the server name, description, or version that appears in /docs:
- Open
config.py - Update
server_name,server_description, andserver_versionfields in theSettingsclass, or set them as environment variablesSERVER_NAME,SERVER_DESCRIPTION,SERVER_VERSION
🔢 Status Codes
HTTP Status Code Reference
| Code | Meaning | When It Occurs |
|---|---|---|
200 OK | Success | All successful GET/POST responses |
201 Created | Created | Workflow creation via n8n API |
204 No Content | Deleted | Workflow or execution deleted |
400 Bad Request | Client error | Malformed JSON in request body |
401 Unauthorized | Auth failure | Missing or invalid Bearer token |
403 Forbidden | Permission denied | Valid token but insufficient scope |
404 Not Found | Not found | Workflow ID or execution ID not found in n8n |
409 Conflict | Duplicate | Creating a workflow with a name that already exists |
422 Unprocessable Entity | Validation error | Pydantic schema validation failure on request |
429 Too Many Requests | Rate limited | Exceeds RATE_LIMIT_REQUESTS per RATE_LIMIT_WINDOW |
500 Internal Server Error | Server error | Unexpected error; check structured logs |
502 Bad Gateway | n8n unreachable | n8n instance is down or unreachable |
503 Service Unavailable | Degraded | n8n connectivity lost; health reports degraded |
MCP Tool Result Codes
| Result Field | Value | Meaning |
|---|---|---|
valid | true / false | Workflow validation pass/fail |
success | true / false | Auto-fix or create operation result |
n8n_reachable | true / false | Health check n8n connectivity |
status | "healthy" / "degraded" | Overall server health |
🚀 Features
🔧 Core Tool Suite (30 Tools)
Workflow Management — 9 Tools
| Tool | Key Parameters | What It Does |
|---|---|---|
list_workflows | active_only, tag, limit | Lists all workflows with ID, name, status, node count |
get_workflow | workflow_id | Returns complete workflow JSON |
create_workflow | workflow_json | Creates workflow from validated JSON |
update_workflow | workflow_id, workflow_json | Updates an existing workflow |
delete_workflow | workflow_id | Permanently deletes a workflow |
activate_workflow | workflow_id | Sets workflow to active (listens for triggers) |
deactivate_workflow | workflow_id | Pauses workflow trigger |
execute_workflow | workflow_id, data | Manually triggers a workflow run |
duplicate_workflow | workflow_id, new_name | Creates a named copy |
Execution & Debugging — 5 Tools
| Tool | Key Parameters | What It Does |
|---|---|---|
list_executions | workflow_id, status, limit | Lists recent executions with timing |
get_execution_details | execution_id | Full node-by-node execution trace |
analyze_workflow_errors | workflow_id | Root cause analysis of failures |
get_execution_metrics | workflow_id | Success rate and performance stats |
get_latest_execution | workflow_id | Status of the most recent run |
Node Documentation — 5 Tools
| Tool | Key Parameters | What It Does |
|---|---|---|
search_nodes | query, category | Find nodes by keyword or type |
get_node_documentation | node_type | Full parameters, examples, credential needs |
list_node_categories | — | Browse all 40+ node categories |
get_node_example | node_type | Ready-to-paste node JSON |
get_expression_guide | topic | n8n expression syntax reference |
Validation & Building — 4 Tools
| Tool | Key Parameters | What It Does |
|---|---|---|
validate_workflow | workflow_json | Pre-deploy structural and syntax check |
auto_fix_workflow | workflow_json, workflow_name | Auto-repairs missing IDs, positions, fields |
build_workflow_template | description | Scaffolds workflow JSON from natural language |
validate_connection | source_node, target_node | Verifies node-to-node connection validity |
AI Intelligence — 5 Tools
| Tool | Key Parameters | What It Does |
|---|---|---|
get_session_context | — | Returns full session history and current state |
get_next_step_recommendations | — | AI-generated suggestions for next action |
analyze_workflow | workflow_id | Deep architectural and quality analysis |
get_workflow_guide | use_case | Step-by-step guide for a specific use case |
search_workflow_templates | query | Find matching template patterns |
Credentials — 3 Tools
| Tool | Key Parameters | What It Does |
|---|---|---|
list_credentials | — | All available credential IDs and types |
get_credential_schema | credential_type | Required fields for a credential type |
get_credential_types_reference | — | Node → credential type mapping |
⚡ Platform Features
- Dual Transport: HTTP/SSE for IDEs and stdio for CLI agents — same 30 tools, both modes
- TTL Cache: Per-resource caching (workflows: 30s, nodes: 3600s, executions: 10s) with automatic background eviction every 5 minutes
- Session Context Memory: Tracks the last 50 tool calls, current workflow state, and action history per session
- Auto-Retry: Up to 3 attempts with exponential backoff (1→2→4 second delays) on
ConnectErrororTimeoutException - Structured Logging: JSON-formatted logs via structlog with
request_id,duration_ms,method,path, andstatuson every request - Request Timing Middleware: Injects
X-Response-TimeandX-Request-IDheaders on every response - GZip Compression: Automatic compression for responses over 1,000 bytes
- CORS: Configurable allowed origins (default:
*for development) - Prometheus Metrics: Cache hit/miss/size counters and active session gauge at
/metrics - Multi-Stage Docker Build: Builder stage → slim production image, running as non-root
mcpuser
🧱 Tech Stack & Architecture
Technology Stack
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Runtime | Python | 3.12 | Application runtime |
| Web Framework | FastAPI | 0.115+ | ASGI server, routing, OpenAPI |
| MCP Runtime | FastMCP | Latest | MCP protocol, tool registration |
| ASGI Server | Uvicorn + uvloop | Latest | High-performance async server |
| HTTP Client | httpx | Latest | Async HTTP calls to n8n API |
| Settings | Pydantic Settings | v2 | Type-safe env var management |
| Retry Logic | Tenacity | Latest | Exponential backoff retry |
| Logging | structlog | Latest | Structured JSON logging |
| Security | python-jose, passlib | Latest | Bearer token validation |
| Containerisation | Docker | 24.x | Multi-stage production image |
| Deployment | Fly.io | — | Cloud deployment platform |
| Orchestration | Docker Compose | 3.9 | Local multi-service deployment |
ASCII Component Architecture Diagram
╔══════════════════════════════════════════════════════════════════════════╗
║ n8n UNIFIED MCP SERVER v1.0.0 ║
╚══════════════════════════════════════════════════════════════════════════╝
┌─────────────────────────────────────────────────────────────────────┐
│ AI CLIENT LAYER │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Gemini CLI │ │ Claude Code │ │ Groq CLI │ │ Antigrav. │ │
│ └──────┬──────┘ └──────┬───────┘ └────┬─────┘ └─────┬─────┘ │
└─────────┼────────────────┼───────────────┼───────────────┼─────────┘
│ │ │ │
└────────────────┴───────────────┴───────────────┘
│
Bearer Token Authorization Header
│
┌──────────────────────────────────▼────────────────────────────────┐
│ FASTAPI APPLICATION │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MIDDLEWARE STACK │ │
│ │ GZipMiddleware → CORSMiddleware → BearerAuthMiddleware │ │
│ │ → RequestTimingMiddleware │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────┐ ┌──────────────┐ ┌──────────┐ ┌────────────┐ │
│ │ /health │ │ /metrics │ │ /info │ │/cache/clear│ │
│ └────────────┘ └──────────────┘ └──────────┘ └────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ FastMCP (mounted at /mcp) │ │
│ │ │ │
│ │ ┌──────────────┐ ┌─────────────┐ ┌──────────────────┐ │ │
│ │ │ workflows │ │ executions │ │ nodes │ │ │
│ │ │ (9 tools) │ │ (5 tools) │ │ (5 tools) │ │ │
│ │ └──────────────┘ └─────────────┘ └──────────────────┘ │ │
│ │ ┌──────────────┐ ┌─────────────┐ ┌──────────────────┐ │ │
│ │ │ validation │ │intelligence │ │ credentials │ │ │
│ │ │ (4 tools) │ │ (5 tools) │ │ (3 tools) │ │ │
│ │ └──────────────┘ └─────────────┘ └──────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│ │ │
┌─────────────▼──────┐ ┌────────▼────────┐ ┌──────▼───────────┐
│ TTL CACHE │ │ CONTEXT MEMORY │ │ STRUCT LOGGER │
│ ┌───────────────┐ │ │ ┌───────────┐ │ │ JSON format │
│ │workflows: 30s │ │ │ │session_id │ │ │ request_id │
│ │nodes: 3600s │ │ │ │action_hx │ │ │ duration_ms │
│ │templates:1800s│ │ │ │wf_context │ │ │ structlog │
│ │executions: 10s│ │ │ │50 actions │ │ └──────────────────┘
│ └───────────────┘ │ │ └───────────┘ │
└─────────────────────┘ └─────────────────┘
│
┌─────────────▼──────────────────────────────────────────────────┐
│ N8N API CLIENT (httpx) │
│ Connection Pool: 20 │ Timeout: 30s │ Retries: 3x EBO │
└─────────────────────────────────────────────────────────────────┘
│
│ REST API v1 · X-N8N-API-KEY Header
▼
┌─────────────────────────────────────────────────────────────────┐
│ n8n INSTANCE (localhost:5678) │
│ /api/v1/workflows │ /api/v1/executions │ /api/v1/nodes │
└─────────────────────────────────────────────────────────────────┘
Data Flow — Validated Workflow Deployment
AI Agent
│
├─ 1. validate_workflow(json)
│ │
│ ├─ [errors found] → auto_fix_workflow(json)
│ │ │
│ │ └─ validate_workflow(fixed_json)
│ │
│ └─ [valid: true]
│
├─ 2. create_workflow(validated_json)
│ │
│ └─ n8n REST POST /api/v1/workflows
│ │
│ └─ returns workflow_id
│
├─ 3. activate_workflow(workflow_id)
│
└─ 4. execute_workflow(workflow_id) → get_latest_execution()
🛠️ Workflow & Implementation
Complete Implementation Flow
-
Environment Bootstrap —
main.pycallssetup_logging()andget_settings()which initialises the Pydantic Settings singleton from.env. The@lru_cache(maxsize=1)decorator ensures settings are loaded exactly once. -
MCP Server Instantiation —
FastMCP(name=settings.server_name)creates the MCP protocol handler. This object registers all tool schemas and handles JSON-RPC dispatch. -
Tool Module Registration — Six
register_*_tools(mcp)functions are called sequentially. Each function uses Python closures to bind MCP tool decorators (@mcp.tool(description=...)) to async handler functions. -
FastAPI Application Creation —
FastAPI(lifespan=lifespan)creates the ASGI application. Thelifespanasync context manager performs startup (n8n health check, cache eviction task) and shutdown (close httpx client, cancel background tasks). -
Middleware Stack Assembly — Middleware is applied in reverse registration order. The effective chain is:
BearerAuthMiddleware→RequestTimingMiddleware→CORSMiddleware→GZipMiddleware→ route handler. -
Bearer Auth Middleware — Intercepts every request. If
MCP_BEARER_TOKENis set, it extracts theAuthorization: Bearer <token>header and compares it using constant-time string comparison. Paths/health,/metrics,/docs,/redoc, and/openapi.jsonbypass auth. -
Request Timing Middleware — Records
time.perf_counter()before and after each request. InjectsX-Response-TimeandX-Request-IDheaders. Logs every request with method, path, status code, and duration via structlog. -
MCP Mount —
app.mount("/mcp", mcp.app)attaches the FastMCP ASGI sub-application at the/mcppath prefix. The MCP SSE stream is accessible at/mcp/sse. -
Tool Call Execution Flow:
- AI client sends
POST /mcpwith JSON-RPC tool call - FastMCP routes to the appropriate registered async function
- The tool function calls
get_cache()to check TTL cache - On cache miss: calls
get_n8n_client()to get the shared httpx client - The n8n client executes the REST API call with retry logic
- Result is stored in cache and returned as JSON string
get_context_manager().get_default()records the action in session history
- AI client sends
-
Cache Eviction — A background
asyncio.Taskruns every 300 seconds and callscache.evict_expired(), which scans all entries and removes those past their TTL expiry timestamp. -
Health Probe —
/healthcallsclient.health_check()which hitsGET /api/v1/workflows?limit=1on n8n. If successful,n8n_reachable: trueand statushealthy. On exception, status becomesdegraded. -
Shutdown Sequence — On SIGTERM (Docker stop, Fly.io redeploy), the lifespan context exits: the cache eviction task is cancelled, the httpx client is closed cleanly, and Uvicorn drains in-flight requests before exiting.
🧪 Testing & Validation
Test Suite
| ID | Area | Command | Expected Output | Explanation |
|---|---|---|---|---|
| T-01 | Server Startup | python main.py | server_ready log, port 8000 listening | Confirms all modules load and n8n is reachable |
| T-02 | Health Endpoint | curl http://localhost:8000/health | {"status":"healthy"} | Validates n8n connectivity and server init |
| T-03 | Auth — No Token | curl -X POST http://localhost:8000/mcp | HTTP 401 Missing or invalid Authorization header | Confirms Bearer auth middleware is active |
| T-04 | Auth — Wrong Token | curl -H "Authorization: Bearer wrong" -X POST http://localhost:8000/mcp | HTTP 401 Invalid bearer token | Confirms token comparison works |
| T-05 | Auth — Bypass Health | curl http://localhost:8000/health (no token) | HTTP 200 | Public paths bypass auth correctly |
| T-06 | List Workflows | MCP tool call list_workflows | JSON with total and workflows array | Confirms n8n API integration |
| T-07 | Cache — First Request | list_workflows call #1 | cache_miss in logs | Confirms first call hits n8n |
| T-08 | Cache — Second Request | list_workflows call #2 within 30s | cache_hit in logs | Confirms TTL cache is functioning |
| T-09 | Validate Workflow — Valid | validate_workflow with correct JSON | {"valid": true, "error_count": 0} | Confirms validator accepts well-formed workflows |
| T-10 | Validate Workflow — Invalid | validate_workflow with missing nodes field | {"valid": false, "errors": [...]} | Confirms error detection |
| T-11 | Auto-Fix | auto_fix_workflow on workflow without node IDs | {"success": true, "fixes_applied": [...]} | Confirms ID injection and position assignment |
| T-12 | Session Context | get_session_context after 3 tool calls | action_history with 3 entries | Confirms context tracking |
| T-13 | Metrics Endpoint | curl http://localhost:8000/metrics | Prometheus text with n8n_mcp_cache_hits | Confirms Prometheus format output |
| T-14 | Cache Clear | curl -X POST -H "Authorization: Bearer TOKEN" http://localhost:8000/cache/clear | {"message": "Cache cleared successfully"} | Confirms admin clear operation |
| T-15 | Docker Build | docker build -t n8n-mcp . | Build exits with code 0 | Confirms multi-stage Dockerfile |
| T-16 | Docker Run | docker run -p 8000:8000 -e N8N_API_KEY=... n8n-mcp | /health responds from container | Confirms runtime environment |
| T-17 | Stdio Mode | python main.py --stdio | MCP initialisation on stdin/stdout | Confirms CLI agent transport |
| T-18 | Rate Limiting | 201 rapid requests | Request 201 returns HTTP 429 | Confirms rate limiter threshold |
| T-19 | Retry Logic | Stop n8n mid-request | 3 retry attempts in logs, then error | Confirms tenacity exponential backoff |
| T-20 | n8n Degraded | Stop n8n, hit /health | {"status": "degraded"} | Confirms graceful degradation |
🔍 Validation Summary
The validation pipeline operates in three layers:
Layer 1 — Request Validation (Pydantic) Every incoming request body is validated by Pydantic v2 schemas. Type mismatches, missing required fields, and out-of-range values are caught before any business logic executes. This returns HTTP 422 with field-level error details.
Layer 2 — Workflow Validation (validate_workflow tool)
The _validate_workflow_structure() function checks:
- Presence and format of
nodesarray - Each node has
id,type,name,position, andparametersfields - No duplicate node names
- All connection references point to existing node names
- Expression syntax uses correct
{{ }}wrapper notation - No hardcoded secrets or API keys in node parameters
- Workflow does not exceed
MAX_WORKFLOW_SIZE_KB(default 512 KB)
Results are returned as:
{ "valid": bool, "error_count": int, "warning_count": int,
"errors": [...], "warnings": [...], "fix_suggestions": [...] }
Layer 3 — Auto-Fix (auto_fix_workflow tool)
The _auto_fix() function applies safe mutations:
- Generates UUIDs for nodes missing
idfields - Assigns grid-based
[x, y]positions to unpositioned nodes - Injects missing
parameters: {}on nodes with no parameters - Sets
typeVersionto 1 if absent - Re-runs validation after fixes to report remaining issues
The fix-then-validate cycle ensures the AI agent always knows the exact state before calling create_workflow.
🧰 Verification Testing Tools & Commands
curl Command Reference
1. Full health check with verbose output:
curl -v http://localhost:8000/health
2. Authenticated MCP info:
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/info
3. Prometheus metrics scrape:
curl http://localhost:8000/metrics
4. Clear server cache (admin):
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/cache/clear
5. Test auth rejection:
curl -X POST http://localhost:8000/mcp -H "Content-Type: application/json" -d '{}'
6. View Swagger UI (open in browser):
http://localhost:8000/docs
7. Check Docker container health:
docker inspect --format='{{json .State.Health}}' n8n-unified-mcp-server
8. View structured logs (Docker):
docker logs -f n8n-unified-mcp-server | python -m json.tool
9. Fly.io live logs:
fly logs --app n8n-unified-mcp-server
10. Test stdio mode (pipe):
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python main.py --stdio
11. Monitor cache hit rate:
watch -n 5 "curl -s http://localhost:8000/metrics | grep cache"
12. Simulate rate limit (Linux):
for i in $(seq 1 205); do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/health; done
🧯 Troubleshooting & Debugging
| Symptom | Likely Cause | Resolution |
|---|---|---|
HTTP 401 Missing Authorization header | Bearer token not set in client config | Add Authorization: Bearer YOUR_TOKEN header to AI client MCP config |
HTTP 401 Invalid bearer token | Wrong token value in client config | Verify MCP_BEARER_TOKEN in .env matches client config |
/health returns "status": "degraded" | n8n instance is unreachable | Verify n8n is running: curl http://localhost:5678/healthz |
N8NAPIError: 401 | Invalid or expired N8N_API_KEY | Regenerate API key at n8n → Settings → API |
N8NAPIError: 404 | Wrong N8N_BASE_URL | Confirm N8N_BASE_URL in .env matches your n8n URL |
validate_workflow fails with Invalid JSON | Workflow JSON has syntax errors | Use a JSON validator tool (jsonlint.com) before passing to the tool |
| Cache never hits (all misses) | CACHE_ENABLED=false in env | Set CACHE_ENABLED=true in .env |
| Server uses wrong settings | Multiple .env files or env vars set at OS level | OS-level env vars override .env; unset or check `env |
ModuleNotFoundError: No module named 'mcp' | Dependencies not installed | Run pip install -r requirements.txt in your active virtualenv |
| Docker container exits immediately | Missing N8N_API_KEY env var | Pass -e N8N_API_KEY=your_key or use docker-compose with .env |
| SSE connection drops after 30s | Nginx/proxy timeout | Set proxy_read_timeout 3600; in Nginx config or use Fly.io directly |
| stdio mode not working in Gemini CLI | Wrong transport configuration | Gemini CLI uses HTTP; only Claude Code CLI needs --stdio |
| High memory usage | Cache growing unboundedly | Reduce CACHE_TTL_* values or enable Redis with explicit eviction |
pydantic_core.InitErrorDetails on startup | .env field name mismatch | Pydantic maps N8N_API_KEY → n8n_api_key; check spelling |
Debug Mode
Enable debug logging for maximum verbosity:
LOG_LEVEL=DEBUG LOG_FORMAT=console python main.py
In debug mode, every cache hit/miss, every n8n API request/response, and every tool call is logged with full parameter detail.
🔒 Security & Secrets
Authentication Model
The server uses stateless Bearer Token authentication. A single shared secret (MCP_BEARER_TOKEN) is set on the server and configured identically in each AI client. There is no user database, no session tokens, and no token rotation — this is intentional for simplicity in the MCP context.
Security Architecture
Request → BearerAuthMiddleware → Token extraction → Constant-time comparison → Allow/Deny
The comparison does NOT use == (which is vulnerable to timing attacks). The token is extracted with auth_header[7:] and compared. For production, replace with hmac.compare_digest(token, settings.mcp_bearer_token).
Secret Management Rules
| Rule | Description |
|---|---|
Never commit .env | .gitignore includes .env by default |
| Never hardcode in code | All secrets must come from env vars |
| Never log secrets | Structured logger never includes token or API key values |
| Rotate tokens regularly | Change MCP_BEARER_TOKEN periodically; update all client configs |
| Use Fly.io secrets | On Fly.io, use fly secrets set — never put secrets in fly.toml |
What Is Protected
N8N_API_KEY— passed asX-N8N-API-KEYheader in n8n calls; never exposed to MCP clientsMCP_BEARER_TOKEN— hashed comparison only; never echoed in responses or logs- n8n credentials (OAuth tokens, API keys stored in n8n) — only
list_credentialsreturns IDs and types, never secret values
What Is Public
/health— intentionally unauthenticated for load balancer probes/metrics— intentionally unauthenticated for Prometheus scraping/docsand/redoc— OpenAPI schema is public; no operations can be executed without a token
☁️ Deployment
Option 1 — Local (Development)
python main.py
Server: http://localhost:8000/mcp
Option 2 — Docker
Build the production image:
docker build -t n8n-mcp-server .
Run the container:
docker run -d \
--name n8n-unified-mcp-server \
-p 8000:8000 \
-e N8N_API_KEY=your_key \
-e N8N_BASE_URL=http://host.docker.internal:5678 \
-e MCP_BEARER_TOKEN=your_token \
-e LOG_FORMAT=json \
n8n-mcp-server
Docker image details:
- Multi-stage build:
builderstage compiles deps,productionstage runs them - Base image:
python:3.12-slim(~180 MB final image) - Runs as non-root user
mcpuserfor security - Built-in
HEALTHCHECKusing Python'surllib.request EXPOSE 8000documented in Dockerfile
Option 3 — Docker Compose
docker-compose up -d
The docker-compose.yml mounts environment variables from .env, sets host.docker.internal:host-gateway for local n8n connectivity, and includes a health check with 15-second interval.
Option 4 — Fly.io (Recommended for Production)
One-time setup:
curl -L https://fly.io/install.sh | sh
fly auth login
fly launch --no-deploy
Set secrets (never in fly.toml):
fly secrets set N8N_API_KEY=your_n8n_api_key
fly secrets set MCP_BEARER_TOKEN=your_secure_token
fly secrets set N8N_BASE_URL=https://your-n8n-instance.com
Deploy:
fly deploy
Monitor:
fly status
fly logs
fly open /health
Fly.io Configuration (fly.toml):
| Setting | Value | Rationale |
|---|---|---|
primary_region | sin (Singapore) | Closest to India; low latency |
auto_stop_machines | false | Zero cold starts; always-on |
min_machines_running | 1 | At least one machine always warm |
vm.size | shared-cpu-1x | Free tier; sufficient for MCP workload |
vm.memory | 512mb | Comfortable for Python + httpx pool |
hard_limit | 200 connections | Rate limit matches RATE_LIMIT_REQUESTS |
Production URL: https://n8n-unified-mcp-server.fly.dev/mcp
Option 5 — Cloudflare Workers
The wrangler.toml file enables deployment to Cloudflare Workers edge network. Note: Cloudflare Workers has limitations with Python ASGI apps — this requires the Cloudflare Python Workers runtime or a custom adaptation. Use wrangler deploy after configuring the account ID in wrangler.toml.
⚡ Quick-Start Cheat Sheet
# 1. Clone & install
git clone https://github.com/your-org/n8n-unified-mcp-server && cd n8n-unified-mcp-server
pip install -r requirements.txt
# 2. Configure
echo "N8N_BASE_URL=http://localhost:5678" > .env
echo "N8N_API_KEY=your_key_here" >> .env
echo "MCP_BEARER_TOKEN=your_token_here" >> .env
# 3. Start
python main.py
# 4. Verify
curl http://localhost:8000/health
# 5. Connect (Claude Code)
# Add to claude_desktop_config.json:
# { "mcpServers": { "n8n": { "type": "http", "url": "http://localhost:8000/mcp",
# "headers": { "Authorization": "Bearer your_token_here" } } } }
# 6. Test in AI client
# "List all my n8n workflows"
# "Create a webhook workflow that sends Slack alerts"
# "Debug why my Invoice Processor workflow keeps failing"
🧾 Usage Notes
Best Practices for AI Agents (from AGENTS.md)
-
Always validate before creating — Never call
create_workflowwithout first callingvalidate_workflow. Fix all errors withauto_fix_workflowbefore deploying. -
Fetch before modifying — Always call
get_workflowbeforeupdate_workflowto capture current state. Never modify a workflow you haven't fetched in the current session. -
Use node documentation — Before adding any node type, call
get_node_documentationorget_node_exampleto get exact parameters. This prevents broken node configurations. -
Check session context first — Begin each session with
get_session_context. Callget_next_step_recommendationswhen unsure what to do next. -
Debug systematically — When a workflow fails: (a) call
analyze_workflow_errorsfor root cause, (b) callget_execution_detailsfor node-level detail, (c) fix withupdate_workflow, (d) re-test withexecute_workflow.
n8n Expression Rules
- Wrap all expressions in
{{ }}delimiters - Use
$json.fieldNamefor current node item data - Use
$node['NodeName'].json.fieldfor other node outputs - Use
$env.VARIABLE_NAMEfor environment variable injection - Never hardcode API keys, passwords, or tokens in node parameters
Example Natural Language Prompts That Work
"List all my n8n workflows""Create a webhook workflow that monitors form submissions and sends Gmail alerts""Show me all failed executions in the last hour""Debug why my Invoice Processor workflow keeps failing""Get the node documentation for Gmail""Validate this workflow JSON before I create it: {...}""Build a workflow template for an AI agent chatbot""What should I do next to improve my current workflow?""Show me the n8n expression syntax for mapping arrays""Analyze my AI Outreach Engine workflow for issues"
🧠 Performance & Optimization
Cache Strategy
| Resource Type | TTL | Rationale |
|---|---|---|
| Workflow list | 30 seconds | Changes occasionally; short TTL keeps data fresh |
| Workflow detail | 30 seconds | Same as list |
| Node documentation | 3600 seconds (1 hr) | Stable; rarely changes between n8n releases |
| Template data | 1800 seconds (30 min) | Semi-static reference data |
| Execution list | 10 seconds | Frequently updated; very short TTL |
Connection Pooling
The httpx.AsyncClient is a singleton (via asyncio.Lock-protected lazy init). It maintains a pool of up to 20 connections with 10 keepalive connections and 30-second keepalive expiry. This means repeated tool calls do not incur TCP handshake overhead.
Async Architecture
Every tool function is async def. All n8n API calls use await. The cache uses asyncio.Lock for thread safety without blocking. The result is that a single Python process can handle hundreds of concurrent tool calls from multiple AI clients without blocking.
Scaling Recommendations
| Scenario | Recommendation |
|---|---|
| Single user, local | 1 Uvicorn worker (default) |
| Team use, 5-10 concurrent | 4 workers (default WORKERS=4) |
| Production, 50+ concurrent | Enable REDIS_URL for shared cache; run 2+ Fly.io machines |
| High-volume automation | Add dedicated Redis instance, increase N8N_MAX_CONNECTIONS to 50 |
Startup Time
The server performs one n8n health check during startup (the lifespan context). On a healthy system this adds ~50ms to startup. This warm-up ensures the first tool call does not experience a cold n8n connection.
🌟 Enhancements & Features
Currently Implemented
- ✅ 30 MCP tools across 6 functional categories
- ✅ Dual transport (HTTP/SSE + stdio)
- ✅ TTL cache with background eviction
- ✅ Session context memory (50-action sliding window)
- ✅ Bearer token authentication
- ✅ Workflow validation + auto-fix pipeline
- ✅ Prometheus metrics endpoint
- ✅ Structured JSON logging
- ✅ Multi-stage Docker build (non-root user)
- ✅ Fly.io one-command deployment with always-on config
- ✅ GZip response compression
- ✅ CORS middleware
- ✅ Request timing headers
- ✅ Retry with exponential backoff
Planned Enhancements
- 🔲 Redis cache backend for horizontal scaling
- 🔲 JWT-based authentication with token expiry
- 🔲 Per-client session isolation (currently all clients share default session)
- 🔲 WebSocket transport for real-time execution streaming
- 🔲 n8n credential creation tool (currently read-only)
- 🔲 Bulk workflow import/export tool
- 🔲 AI-powered workflow diff and changelog generation
- 🔲 OpenTelemetry distributed tracing integration
- 🔲 Rate limiting per-client (currently global)
🧩 Maintenance & Future Work
Routine Maintenance Tasks
| Task | Frequency | Command / Action |
|---|---|---|
| Update Python dependencies | Monthly | pip install -r requirements.txt --upgrade |
Rotate MCP_BEARER_TOKEN | Quarterly | Update .env and all AI client configs |
Rotate N8N_API_KEY | Quarterly | Regenerate in n8n UI, update .env |
| Review cache hit rate | Weekly | Check /metrics — target > 60% hit rate |
| Check log volume | Weekly | Large log files indicate unexpected traffic |
| Update Fly.io machine size | As needed | fly scale vm shared-cpu-2x for growth |
When to Scale
- Cache miss rate consistently > 70% — decrease TTL values or add Redis
- Response time > 200ms on cached requests — increase worker count
- Memory > 400MB on 512MB instance — upgrade Fly.io VM size
- n8n health check timing out > 5% of the time — check n8n instance resources
Monitoring Checklist
-
/healthreturns"status": "healthy"on every deploy -
n8n_mcp_cache_hit_rate> 60% in steady state - No
HTTP 500errors in logs - Fly.io machine count ≥
min_machines_running -
N8N_API_KEYandMCP_BEARER_TOKENare set as Fly.io secrets (not infly.toml)
🏆 Milestones
| Milestone | Description | Status |
|---|---|---|
| M-01 | Core MCP server with FastAPI + FastMCP | ✅ Complete |
| M-02 | All 9 workflow management tools | ✅ Complete |
| M-03 | All 5 execution & debugging tools | ✅ Complete |
| M-04 | All 5 node documentation tools (40+ nodes) | ✅ Complete |
| M-05 | Validation + auto-fix pipeline (4 tools) | ✅ Complete |
| M-06 | AI intelligence tools + session context (5 tools) | ✅ Complete |
| M-07 | Credentials tools (3 tools) | ✅ Complete |
| M-08 | Bearer auth middleware | ✅ Complete |
| M-09 | TTL cache with background eviction | ✅ Complete |
| M-10 | Structured logging + Prometheus metrics | ✅ Complete |
| M-11 | Multi-stage Docker build + Compose | ✅ Complete |
| M-12 | Fly.io deployment config | ✅ Complete |
| M-13 | Dual transport (HTTP/SSE + stdio) | ✅ Complete |
| M-14 | Client config docs (5 clients) | ✅ Complete |
| M-15 | Redis cache backend | 🔲 Planned |
| M-16 | JWT auth with expiry | 🔲 Planned |
| M-17 | OpenTelemetry tracing | 🔲 Planned |
🧮 High-Level Architecture
Component Interaction Map
┌─────────────────────────────────────────────────────────────────────┐
│ DEPLOYMENT LAYER │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │
│ │ Fly.io Machine │ │ Docker / Compose│ │ Local Dev │ │
│ │ 512MB · 1 vCPU │ │ python:3.12-slim │ │ .venv │ │
│ └────────┬─────────┘ └────────┬──────────┘ └──────┬───────┘ │
└───────────┼──────────────────────┼───────────────────────┼──────────┘
│ │ │
└──────────────────────┴───────────────────────┘
│
HTTPS / HTTP :8000
│
┌──────────────────────────────────▼────────────────────────────────────┐
│ APPLICATION LAYER │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ Uvicorn ASGI Server │ │
│ │ 4 workers · uvloop event loop · access_log=False │ │
│ └──────────────────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────▼───────────────────────────────────────┐ │
│ │ FastAPI Application (main.py) │ │
│ │ │ │
│ │ GET /health GET /metrics GET /info POST /cache/clear │ │
│ │ GET /docs GET /redoc GET /openapi.json │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────────────┐ │ │
│ │ │ FastMCP Sub-Application (mounted at /mcp) │ │ │
│ │ │ POST /mcp · GET /mcp/sse · MCP 2025-06-18 spec │ │ │
│ │ └────────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────────────────┐ │
│ │ config.py │ │ core/cache.py │ │ core/context.py │ │
│ │ Pydantic v2 │ │ TTLCache │ │ SessionContext │ │
│ │ lru_cache(1) │ │ asyncio.Lock │ │ 50-action history │ │
│ └─────────────────┘ └──────────────────┘ └────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ core/n8n_client.py │ │
│ │ httpx.AsyncClient · ConnectionPool(20) · tenacity retry(3) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘
│
n8n REST API v1
X-N8N-API-KEY Header Auth
│
┌──────────────────────────────────▼────────────────────────────────────┐
│ n8n INSTANCE (:5678) │
│ /api/v1/workflows /api/v1/executions /api/v1/nodes /api/v1/creds │
└────────────────────────────────────────────────────────────────────────┘
🗂️ Folder Structure
n8n-unified-mcp-server/
│
├── 📄 main.py # FastAPI app + FastMCP mount + middleware + routes
├── 📄 config.py # Pydantic Settings — all env vars with defaults
├── 📄 requirements.txt # Python dependencies
├── 📄 Dockerfile # Multi-stage build (builder + production stages)
├── 📄 docker-compose.yml # Local Docker Compose with health checks
├── 📄 fly.toml # Fly.io deployment config (Singapore region)
├── 📄 wrangler.toml # Cloudflare Workers deployment config
├── 📄 start.sh # Linux/macOS startup script
├── 📄 start.bat # Windows startup script
├── 📄 AGENTS.md # AI agent system prompt and rules for n8n dev
├── 📄 README.md # This file
├── 📄 .gitignore # Excludes .env, __pycache__, .venv, *.pyc
│
├── 📁 core/ # Core infrastructure modules
│ ├── 📄 __init__.py
│ ├── 📄 cache.py # TTLCache class + cached() helper + get_cache()
│ ├── 📄 context.py # SessionContext + WorkflowContext dataclasses
│ ├── 📄 logger.py # structlog setup + get_logger() factory
│ └── 📄 n8n_client.py # N8NClient (httpx) + N8NAPIError + get_n8n_client()
│
├── 📁 tools/ # MCP tool registration modules
│ ├── 📄 __init__.py # Re-exports all register_*_tools functions
│ ├── 📄 workflows.py # 9 workflow management tools
│ ├── 📄 executions.py # 5 execution debugging tools
│ ├── 📄 nodes.py # 5 node documentation tools (40+ node types)
│ ├── 📄 validation.py # 4 validation + auto-fix tools
│ ├── 📄 intelligence.py # 5 AI intelligence + session tools
│ └── 📄 credentials.py # 3 credential management tools
│
└── 📁 middleware/ # Custom FastAPI middleware
├── 📄 __init__.py
└── (auth and timing in main.py as inline middleware)
🧭 How to Demonstrate Live
Demo Sequence (Exact Commands)
Step 1 — Start the server and confirm health:
python main.py
curl http://localhost:8000/health
Step 2 — Open Swagger UI in browser:
http://localhost:8000/docs
Click Authorize, enter Bearer your_token_here
Step 3 — In your AI client (Claude Code example), run:
"List all my n8n workflows"
Expected: JSON list of all workflows with IDs, names, active status
Step 4 — Demonstrate validation pipeline:
"Validate this workflow JSON: { \"nodes\": [], \"connections\": {} }"
Expected: Validation error — missing trigger node, empty nodes array
Step 5 — Demonstrate auto-fix:
"Auto-fix this workflow: { \"name\": \"Test\", \"nodes\": [{ \"type\": \"n8n-nodes-base.webhook\", \"name\": \"Webhook\" }] }"
Expected: Fixed workflow with injected IDs and positions
Step 6 — Create and activate a real workflow:
"Build a workflow template for: monitor a webhook and log the payload to a Slack channel"
Then: "Create this workflow" → "Activate workflow <id>"
Step 7 — Show metrics:
curl http://localhost:8000/metrics
Expected: Non-zero cache hits from the demo calls
Step 8 — Show session context:
"Show me the session context and what we've done so far"
Expected: action_history with all 6+ prior tool calls listed
💡 Summary, Closure & Compliance
Project Summary
The n8n Unified MCP Server delivers a production-ready, single-endpoint gateway that eliminates the configuration fragmentation of connecting multiple AI coding assistants to n8n. With 30 MCP tools, dual-transport support, an intelligent caching layer, session-aware context memory, and a validate-before-deploy workflow safety net, it provides everything a professional AI-assisted n8n developer needs.
Compliance Checklist
| Category | Requirement | Status |
|---|---|---|
| Security | Bearer token authentication on all MCP endpoints | ✅ |
| Security | No secrets in code or logs | ✅ |
| Security | Non-root Docker user | ✅ |
| Reliability | Automatic retry on transient failures | ✅ |
| Reliability | Graceful degradation when n8n is unreachable | ✅ |
| Observability | Structured JSON logging on all requests | ✅ |
| Observability | Prometheus metrics endpoint | ✅ |
| Observability | Health check endpoint for load balancers | ✅ |
| Performance | TTL caching for all n8n API responses | ✅ |
| Performance | Async connection pooling (no blocking I/O) | ✅ |
| Portability | Docker + Docker Compose support | ✅ |
| Portability | Fly.io cloud deployment config | ✅ |
| Compatibility | Works with 5+ AI clients out of the box | ✅ |
| Data Quality | Validate + auto-fix before any workflow deploy | ✅ |
| Documentation | Swagger UI + ReDoc auto-generated | ✅ |
Key Design Decisions
- FastMCP over raw MCP SDK — FastMCP provides a decorator-based DX that matches FastAPI's approach, keeping tool registration clean and co-located with business logic.
- In-memory cache over Redis — Zero additional infrastructure for single-instance deployments; Redis URL is an optional upgrade path.
- Stateless bearer token — Simplest possible auth model for the MCP context; no user DB, no session store, maximum compatibility.
- Python 3.12 — Latest stable with improved asyncio performance and better type inference.
lru_cache(maxsize=1)onget_settings()— Settings are read once at startup and shared as a singleton, avoiding repeated.envfile I/O.
Built with ❤️ for the n8n + AI developer community