convez.ai
MCP ServerAutomaçãoAvançado
anshwysmcbel2710

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 GitHub
InicialPluginScore · de 0 a 100

Servidor 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-server

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 7 meses
Versão
—
Issues abertas
1
Contribuidores
1

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

n8n MCP Server Banner Python FastAPI MCP Protocol Docker Fly.io License

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

#Section#Section
1🧩 Project Overview16🔒 Security & Secrets
2🎯 Objectives & Goals17☁️ Deployment
3✅ Acceptance Criteria18⚡ Quick-Start Cheat Sheet
4💻 Prerequisites19🧾 Usage Notes
5⚙️ Installation & Setup20🧠 Performance & Optimization
6🔗 API Documentation21🌟 Enhancements & Features
7🖥️ UI / Frontend22🧩 Maintenance & Future Work
8🔢 Status Codes23🏆 Milestones
9🚀 Features24🧮 High-Level Architecture
10🧱 Tech Stack & Architecture25🗂️ Folder Structure
11🛠️ Workflow & Implementation26🧭 How to Demonstrate Live
12🧪 Testing & Validation27💡 Summary, Closure & Compliance
13🔍 Validation Summary——
14🧰 Verification Testing Tools & Commands——
15🧯 Troubleshooting & Debugging——

🧩 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

#ObjectivePriorityOutcome
1Provide a single MCP endpoint for all AI clients🔴 CriticalOne URL, one token, all clients
2Expose all n8n REST API v1 capabilities as MCP tools🔴 Critical30 tools across 6 categories
3Ensure zero data loss during workflow operations🔴 CriticalValidate → Auto-fix → Deploy pipeline
4Enable context-aware AI assistance across tool calls🟡 HighSession context with 50-action history
5Achieve sub-100 ms response for cached operations🟡 HighTTL cache with resource-specific windows
6Support cloud-native deployment with zero cold starts🟡 HighFly.io always-on + Docker multi-stage
7Provide Prometheus-compatible observability🟢 Medium/metrics, /health, structured logs
8Allow optional Redis cache for horizontal scaling🟢 MediumRedis URL config flag

✅ Acceptance Criteria

#CriterionVerification MethodStatus
AC-01Server starts on port 8000 and responds at /healthcurl http://localhost:8000/health returns {"status":"healthy"}✅
AC-02All 30 MCP tools are registered and discoverableMCP client tool list returns 30 entries✅
AC-03Bearer token authentication rejects invalid tokensUnauthenticated request returns HTTP 401✅
AC-04/health and /docs endpoints bypass authenticationDirect curl to /health without token returns 200✅
AC-05validate_workflow catches structural errors before deployMalformed JSON returns {"valid": false, "errors": [...]}✅
AC-06auto_fix_workflow repairs missing IDs and positionsFixed workflow passes validate_workflow with zero errors✅
AC-07Cache returns hit on second identical request within TTL/metrics shows incrementing cache_hits counter✅
AC-08Session context persists across multiple tool callsget_session_context reflects all prior actions in session✅
AC-09n8n connectivity failure returns {"status": "degraded"}Stopping n8n; /health degrades gracefully✅
AC-10Docker image builds and runs without errorsdocker build + docker run succeeds, /health responds✅
AC-11Fly.io deployment is reachable at HTTPS endpointhttps://n8n-unified-mcp-server.fly.dev/health returns 200✅
AC-12Prometheus metrics are exposed in correct text formatcurl /metrics returns valid Prometheus exposition format✅

💻 Prerequisites

System Requirements

ComponentMinimumRecommended
Python3.113.12
RAM256 MB512 MB+
Disk200 MB500 MB
n8n Instancev1.0+Latest stable
Docker (optional)24.xLatest
Node.js (for npx tools)18.x20 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 python or python3
  • pip package manager available
  • n8n running and accessible (verify at http://localhost:5678)
  • Docker installed (optional — for containerised deployment)
  • Fly CLI installed (optional — for cloud deployment)
  • curl or 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:

PackagePurpose
mcpModel Context Protocol core runtime
fastapiASGI web framework
httpxAsync HTTP client for n8n API calls
pydantic / pydantic-settingsType-safe config & validation
tenacityRetry logic with exponential backoff
structlogStructured JSON logging
python-joseJWT / bearer token security
passlibPassword / secret hashing utilities
typing-extensionsBackported 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:

VariableRequiredDefaultDescription
N8N_API_KEY✅ Yes—n8n REST API key from Settings → API
N8N_BASE_URL✅ Yeshttp://localhost:5678Base URL of your n8n instance
MCP_BEARER_TOKEN⚠️ Strongly recommended—Shared secret for MCP client auth
MCP_HOSTNo0.0.0.0Server bind host
MCP_PORTNo8000Server listen port
LOG_LEVELNoINFODEBUG, INFO, WARNING, ERROR
LOG_FORMATNoconsoleconsole (dev) or json (prod)
CACHE_ENABLEDNotrueToggle response caching
CACHE_TTL_WORKFLOWSNo30Workflow list cache TTL in seconds
CACHE_TTL_NODESNo3600Node docs cache TTL (1 hour)
CACHE_TTL_EXECUTIONSNo10Execution cache TTL
CACHE_TTL_TEMPLATESNo1800Template cache TTL (30 min)
REDIS_URLNo—Optional Redis URL for multi-instance cache
WORKERSNo4Uvicorn worker processes
N8N_API_TIMEOUTNo30HTTP timeout for n8n calls (seconds)
N8N_API_RETRIESNo3Retry attempts on transient failure
N8N_MAX_CONNECTIONSNo20HTTP connection pool size
ENABLE_WORKFLOW_VALIDATIONNotrueEnable pre-deploy validation
ENABLE_AUTO_FIXNotrueEnable auto-fix tool
ENABLE_CONTEXT_MEMORYNotrueEnable session context tracking
ENABLE_TEMPLATE_SEARCHNotrueEnable template search intelligence
RATE_LIMIT_ENABLEDNotrueEnable rate limiting
RATE_LIMIT_REQUESTSNo200Max requests per window
RATE_LIMIT_WINDOWNo60Rate 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

MethodEndpointAuth RequiredDescription
GET/health❌ NoServer + n8n connectivity check
GET/metrics❌ NoPrometheus-format cache & session metrics
GET/info❌ NoServer 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❌ NoSwagger UI
GET/redoc❌ NoReDoc 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)

HeaderDescription
X-Request-IDUnique request identifier for tracing
X-Response-TimeServer processing time in milliseconds
X-ServerServer 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 🔒 Authorize button, enter Bearer <your_token>
  • Styling: Default FastAPI Swagger theme; to customise, override the swagger_ui_parameters in the FastAPI() constructor in main.py

ReDoc (/redoc)

  • Location: http://localhost:8000/redoc
  • Purpose: Cleaner, read-only API reference documentation
  • Styling: Can be customised via redoc_url and redoc_js_url in 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, and server_version fields in the Settings class, or set them as environment variables SERVER_NAME, SERVER_DESCRIPTION, SERVER_VERSION

🔢 Status Codes

HTTP Status Code Reference

CodeMeaningWhen It Occurs
200 OKSuccessAll successful GET/POST responses
201 CreatedCreatedWorkflow creation via n8n API
204 No ContentDeletedWorkflow or execution deleted
400 Bad RequestClient errorMalformed JSON in request body
401 UnauthorizedAuth failureMissing or invalid Bearer token
403 ForbiddenPermission deniedValid token but insufficient scope
404 Not FoundNot foundWorkflow ID or execution ID not found in n8n
409 ConflictDuplicateCreating a workflow with a name that already exists
422 Unprocessable EntityValidation errorPydantic schema validation failure on request
429 Too Many RequestsRate limitedExceeds RATE_LIMIT_REQUESTS per RATE_LIMIT_WINDOW
500 Internal Server ErrorServer errorUnexpected error; check structured logs
502 Bad Gatewayn8n unreachablen8n instance is down or unreachable
503 Service UnavailableDegradedn8n connectivity lost; health reports degraded

MCP Tool Result Codes

Result FieldValueMeaning
validtrue / falseWorkflow validation pass/fail
successtrue / falseAuto-fix or create operation result
n8n_reachabletrue / falseHealth check n8n connectivity
status"healthy" / "degraded"Overall server health

🚀 Features

🔧 Core Tool Suite (30 Tools)

Workflow Management — 9 Tools

ToolKey ParametersWhat It Does
list_workflowsactive_only, tag, limitLists all workflows with ID, name, status, node count
get_workflowworkflow_idReturns complete workflow JSON
create_workflowworkflow_jsonCreates workflow from validated JSON
update_workflowworkflow_id, workflow_jsonUpdates an existing workflow
delete_workflowworkflow_idPermanently deletes a workflow
activate_workflowworkflow_idSets workflow to active (listens for triggers)
deactivate_workflowworkflow_idPauses workflow trigger
execute_workflowworkflow_id, dataManually triggers a workflow run
duplicate_workflowworkflow_id, new_nameCreates a named copy

Execution & Debugging — 5 Tools

ToolKey ParametersWhat It Does
list_executionsworkflow_id, status, limitLists recent executions with timing
get_execution_detailsexecution_idFull node-by-node execution trace
analyze_workflow_errorsworkflow_idRoot cause analysis of failures
get_execution_metricsworkflow_idSuccess rate and performance stats
get_latest_executionworkflow_idStatus of the most recent run

Node Documentation — 5 Tools

ToolKey ParametersWhat It Does
search_nodesquery, categoryFind nodes by keyword or type
get_node_documentationnode_typeFull parameters, examples, credential needs
list_node_categories—Browse all 40+ node categories
get_node_examplenode_typeReady-to-paste node JSON
get_expression_guidetopicn8n expression syntax reference

Validation & Building — 4 Tools

ToolKey ParametersWhat It Does
validate_workflowworkflow_jsonPre-deploy structural and syntax check
auto_fix_workflowworkflow_json, workflow_nameAuto-repairs missing IDs, positions, fields
build_workflow_templatedescriptionScaffolds workflow JSON from natural language
validate_connectionsource_node, target_nodeVerifies node-to-node connection validity

AI Intelligence — 5 Tools

ToolKey ParametersWhat It Does
get_session_context—Returns full session history and current state
get_next_step_recommendations—AI-generated suggestions for next action
analyze_workflowworkflow_idDeep architectural and quality analysis
get_workflow_guideuse_caseStep-by-step guide for a specific use case
search_workflow_templatesqueryFind matching template patterns

Credentials — 3 Tools

ToolKey ParametersWhat It Does
list_credentials—All available credential IDs and types
get_credential_schemacredential_typeRequired 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 ConnectError or TimeoutException
  • Structured Logging: JSON-formatted logs via structlog with request_id, duration_ms, method, path, and status on every request
  • Request Timing Middleware: Injects X-Response-Time and X-Request-ID headers 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

LayerTechnologyVersionPurpose
RuntimePython3.12Application runtime
Web FrameworkFastAPI0.115+ASGI server, routing, OpenAPI
MCP RuntimeFastMCPLatestMCP protocol, tool registration
ASGI ServerUvicorn + uvloopLatestHigh-performance async server
HTTP ClienthttpxLatestAsync HTTP calls to n8n API
SettingsPydantic Settingsv2Type-safe env var management
Retry LogicTenacityLatestExponential backoff retry
LoggingstructlogLatestStructured JSON logging
Securitypython-jose, passlibLatestBearer token validation
ContainerisationDocker24.xMulti-stage production image
DeploymentFly.io—Cloud deployment platform
OrchestrationDocker Compose3.9Local 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

  1. Environment Bootstrap — main.py calls setup_logging() and get_settings() which initialises the Pydantic Settings singleton from .env. The @lru_cache(maxsize=1) decorator ensures settings are loaded exactly once.

  2. MCP Server Instantiation — FastMCP(name=settings.server_name) creates the MCP protocol handler. This object registers all tool schemas and handles JSON-RPC dispatch.

  3. 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.

  4. FastAPI Application Creation — FastAPI(lifespan=lifespan) creates the ASGI application. The lifespan async context manager performs startup (n8n health check, cache eviction task) and shutdown (close httpx client, cancel background tasks).

  5. Middleware Stack Assembly — Middleware is applied in reverse registration order. The effective chain is: BearerAuthMiddleware → RequestTimingMiddleware → CORSMiddleware → GZipMiddleware → route handler.

  6. Bearer Auth Middleware — Intercepts every request. If MCP_BEARER_TOKEN is set, it extracts the Authorization: Bearer <token> header and compares it using constant-time string comparison. Paths /health, /metrics, /docs, /redoc, and /openapi.json bypass auth.

  7. Request Timing Middleware — Records time.perf_counter() before and after each request. Injects X-Response-Time and X-Request-ID headers. Logs every request with method, path, status code, and duration via structlog.

  8. MCP Mount — app.mount("/mcp", mcp.app) attaches the FastMCP ASGI sub-application at the /mcp path prefix. The MCP SSE stream is accessible at /mcp/sse.

  9. Tool Call Execution Flow:

    • AI client sends POST /mcp with 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
  10. Cache Eviction — A background asyncio.Task runs every 300 seconds and calls cache.evict_expired(), which scans all entries and removes those past their TTL expiry timestamp.

  11. Health Probe — /health calls client.health_check() which hits GET /api/v1/workflows?limit=1 on n8n. If successful, n8n_reachable: true and status healthy. On exception, status becomes degraded.

  12. 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

IDAreaCommandExpected OutputExplanation
T-01Server Startuppython main.pyserver_ready log, port 8000 listeningConfirms all modules load and n8n is reachable
T-02Health Endpointcurl http://localhost:8000/health{"status":"healthy"}Validates n8n connectivity and server init
T-03Auth — No Tokencurl -X POST http://localhost:8000/mcpHTTP 401 Missing or invalid Authorization headerConfirms Bearer auth middleware is active
T-04Auth — Wrong Tokencurl -H "Authorization: Bearer wrong" -X POST http://localhost:8000/mcpHTTP 401 Invalid bearer tokenConfirms token comparison works
T-05Auth — Bypass Healthcurl http://localhost:8000/health (no token)HTTP 200Public paths bypass auth correctly
T-06List WorkflowsMCP tool call list_workflowsJSON with total and workflows arrayConfirms n8n API integration
T-07Cache — First Requestlist_workflows call #1cache_miss in logsConfirms first call hits n8n
T-08Cache — Second Requestlist_workflows call #2 within 30scache_hit in logsConfirms TTL cache is functioning
T-09Validate Workflow — Validvalidate_workflow with correct JSON{"valid": true, "error_count": 0}Confirms validator accepts well-formed workflows
T-10Validate Workflow — Invalidvalidate_workflow with missing nodes field{"valid": false, "errors": [...]}Confirms error detection
T-11Auto-Fixauto_fix_workflow on workflow without node IDs{"success": true, "fixes_applied": [...]}Confirms ID injection and position assignment
T-12Session Contextget_session_context after 3 tool callsaction_history with 3 entriesConfirms context tracking
T-13Metrics Endpointcurl http://localhost:8000/metricsPrometheus text with n8n_mcp_cache_hitsConfirms Prometheus format output
T-14Cache Clearcurl -X POST -H "Authorization: Bearer TOKEN" http://localhost:8000/cache/clear{"message": "Cache cleared successfully"}Confirms admin clear operation
T-15Docker Builddocker build -t n8n-mcp .Build exits with code 0Confirms multi-stage Dockerfile
T-16Docker Rundocker run -p 8000:8000 -e N8N_API_KEY=... n8n-mcp/health responds from containerConfirms runtime environment
T-17Stdio Modepython main.py --stdioMCP initialisation on stdin/stdoutConfirms CLI agent transport
T-18Rate Limiting201 rapid requestsRequest 201 returns HTTP 429Confirms rate limiter threshold
T-19Retry LogicStop n8n mid-request3 retry attempts in logs, then errorConfirms tenacity exponential backoff
T-20n8n DegradedStop 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 nodes array
  • Each node has id, type, name, position, and parameters fields
  • 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 id fields
  • Assigns grid-based [x, y] positions to unpositioned nodes
  • Injects missing parameters: {} on nodes with no parameters
  • Sets typeVersion to 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

SymptomLikely CauseResolution
HTTP 401 Missing Authorization headerBearer token not set in client configAdd Authorization: Bearer YOUR_TOKEN header to AI client MCP config
HTTP 401 Invalid bearer tokenWrong token value in client configVerify MCP_BEARER_TOKEN in .env matches client config
/health returns "status": "degraded"n8n instance is unreachableVerify n8n is running: curl http://localhost:5678/healthz
N8NAPIError: 401Invalid or expired N8N_API_KEYRegenerate API key at n8n → Settings → API
N8NAPIError: 404Wrong N8N_BASE_URLConfirm N8N_BASE_URL in .env matches your n8n URL
validate_workflow fails with Invalid JSONWorkflow JSON has syntax errorsUse a JSON validator tool (jsonlint.com) before passing to the tool
Cache never hits (all misses)CACHE_ENABLED=false in envSet CACHE_ENABLED=true in .env
Server uses wrong settingsMultiple .env files or env vars set at OS levelOS-level env vars override .env; unset or check `env
ModuleNotFoundError: No module named 'mcp'Dependencies not installedRun pip install -r requirements.txt in your active virtualenv
Docker container exits immediatelyMissing N8N_API_KEY env varPass -e N8N_API_KEY=your_key or use docker-compose with .env
SSE connection drops after 30sNginx/proxy timeoutSet proxy_read_timeout 3600; in Nginx config or use Fly.io directly
stdio mode not working in Gemini CLIWrong transport configurationGemini CLI uses HTTP; only Claude Code CLI needs --stdio
High memory usageCache growing unboundedlyReduce CACHE_TTL_* values or enable Redis with explicit eviction
pydantic_core.InitErrorDetails on startup.env field name mismatchPydantic 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

RuleDescription
Never commit .env.gitignore includes .env by default
Never hardcode in codeAll secrets must come from env vars
Never log secretsStructured logger never includes token or API key values
Rotate tokens regularlyChange MCP_BEARER_TOKEN periodically; update all client configs
Use Fly.io secretsOn Fly.io, use fly secrets set — never put secrets in fly.toml

What Is Protected

  • N8N_API_KEY — passed as X-N8N-API-KEY header in n8n calls; never exposed to MCP clients
  • MCP_BEARER_TOKEN — hashed comparison only; never echoed in responses or logs
  • n8n credentials (OAuth tokens, API keys stored in n8n) — only list_credentials returns IDs and types, never secret values

What Is Public

  • /health — intentionally unauthenticated for load balancer probes
  • /metrics — intentionally unauthenticated for Prometheus scraping
  • /docs and /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: builder stage compiles deps, production stage runs them
  • Base image: python:3.12-slim (~180 MB final image)
  • Runs as non-root user mcpuser for security
  • Built-in HEALTHCHECK using Python's urllib.request
  • EXPOSE 8000 documented 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):

SettingValueRationale
primary_regionsin (Singapore)Closest to India; low latency
auto_stop_machinesfalseZero cold starts; always-on
min_machines_running1At least one machine always warm
vm.sizeshared-cpu-1xFree tier; sufficient for MCP workload
vm.memory512mbComfortable for Python + httpx pool
hard_limit200 connectionsRate 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)

  1. Always validate before creating — Never call create_workflow without first calling validate_workflow. Fix all errors with auto_fix_workflow before deploying.

  2. Fetch before modifying — Always call get_workflow before update_workflow to capture current state. Never modify a workflow you haven't fetched in the current session.

  3. Use node documentation — Before adding any node type, call get_node_documentation or get_node_example to get exact parameters. This prevents broken node configurations.

  4. Check session context first — Begin each session with get_session_context. Call get_next_step_recommendations when unsure what to do next.

  5. Debug systematically — When a workflow fails: (a) call analyze_workflow_errors for root cause, (b) call get_execution_details for node-level detail, (c) fix with update_workflow, (d) re-test with execute_workflow.

n8n Expression Rules

  • Wrap all expressions in {{ }} delimiters
  • Use $json.fieldName for current node item data
  • Use $node['NodeName'].json.field for other node outputs
  • Use $env.VARIABLE_NAME for 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 TypeTTLRationale
Workflow list30 secondsChanges occasionally; short TTL keeps data fresh
Workflow detail30 secondsSame as list
Node documentation3600 seconds (1 hr)Stable; rarely changes between n8n releases
Template data1800 seconds (30 min)Semi-static reference data
Execution list10 secondsFrequently 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

ScenarioRecommendation
Single user, local1 Uvicorn worker (default)
Team use, 5-10 concurrent4 workers (default WORKERS=4)
Production, 50+ concurrentEnable REDIS_URL for shared cache; run 2+ Fly.io machines
High-volume automationAdd 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

TaskFrequencyCommand / Action
Update Python dependenciesMonthlypip install -r requirements.txt --upgrade
Rotate MCP_BEARER_TOKENQuarterlyUpdate .env and all AI client configs
Rotate N8N_API_KEYQuarterlyRegenerate in n8n UI, update .env
Review cache hit rateWeeklyCheck /metrics — target > 60% hit rate
Check log volumeWeeklyLarge log files indicate unexpected traffic
Update Fly.io machine sizeAs neededfly 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

  • /health returns "status": "healthy" on every deploy
  • n8n_mcp_cache_hit_rate > 60% in steady state
  • No HTTP 500 errors in logs
  • Fly.io machine count ≥ min_machines_running
  • N8N_API_KEY and MCP_BEARER_TOKEN are set as Fly.io secrets (not in fly.toml)

🏆 Milestones

MilestoneDescriptionStatus
M-01Core MCP server with FastAPI + FastMCP✅ Complete
M-02All 9 workflow management tools✅ Complete
M-03All 5 execution & debugging tools✅ Complete
M-04All 5 node documentation tools (40+ nodes)✅ Complete
M-05Validation + auto-fix pipeline (4 tools)✅ Complete
M-06AI intelligence tools + session context (5 tools)✅ Complete
M-07Credentials tools (3 tools)✅ Complete
M-08Bearer auth middleware✅ Complete
M-09TTL cache with background eviction✅ Complete
M-10Structured logging + Prometheus metrics✅ Complete
M-11Multi-stage Docker build + Compose✅ Complete
M-12Fly.io deployment config✅ Complete
M-13Dual transport (HTTP/SSE + stdio)✅ Complete
M-14Client config docs (5 clients)✅ Complete
M-15Redis cache backend🔲 Planned
M-16JWT auth with expiry🔲 Planned
M-17OpenTelemetry 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

CategoryRequirementStatus
SecurityBearer token authentication on all MCP endpoints✅
SecurityNo secrets in code or logs✅
SecurityNon-root Docker user✅
ReliabilityAutomatic retry on transient failures✅
ReliabilityGraceful degradation when n8n is unreachable✅
ObservabilityStructured JSON logging on all requests✅
ObservabilityPrometheus metrics endpoint✅
ObservabilityHealth check endpoint for load balancers✅
PerformanceTTL caching for all n8n API responses✅
PerformanceAsync connection pooling (no blocking I/O)✅
PortabilityDocker + Docker Compose support✅
PortabilityFly.io cloud deployment config✅
CompatibilityWorks with 5+ AI clients out of the box✅
Data QualityValidate + auto-fix before any workflow deploy✅
DocumentationSwagger 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) on get_settings() — Settings are read once at startup and shared as a singleton, avoiding repeated .env file I/O.

Built with ❤️ for the n8n + AI developer community

Made with Python MCP Protocol n8n Compatible

Ver o original no GitHub

Bom para

Relacionados