n8n Manager MCP

n8n Manager MCP Server

🇬🇧 English | [🇩🇪 Deutsch](README_de.md) | [🇪🇸 Español](README_es.md) | [🇯🇵 日本語](README_ja.md) | [🇷🇺 Русский](README_ru.md) | [🇫🇷 Français](README_fr.md) | [🇨🇳 简体中文](README_zh.md) | [🇮🇳 हिन्दी](README_hi.md) | [العربية](README_ar.md) | [বাংলা](README_bn.md) | [Português](README_pt.md)

*Part of the ellmos-ai family and the open-bricks umbrella.*

[!NOTE]

For AI Assistants & LLMs: An llms.txt index file is available in the root directory for fast context ingestion, tool catalog references, and directory listings.

MCP (Model Context Protocol) server for managing n8n workflows via AI assistants like Claude, Cursor, and Windsurf.

Quick Navigation

---

System Architecture

The n8n Manager MCP Server operates as a local-first, stdio-connected bridge between AI development environments (Claude Code, Claude Desktop, Cursor, Windsurf) and local or remote n8n instances.

• Process Model: Runs as a Node.js process communicating with its MCP client over standard input/output (stdio) using JSON-RPC 2.0. It inherits the privileges of the process that launches it.
• Mutation Checks: Workflow mutation handlers load local configuration and check read-only mode before making an n8n mutation request. A blocked attempt can still append to the local audit log; configuration loading also uses the filesystem.
• Multi-Instance Router: Routes calls to configured n8n instances using local server profiles. API keys in servers.json are plaintext; config updates use a temporary file and rename.
• Offline Node Catalog: Lists common n8n node types and short descriptions by category (n8n_describe_nodes) without a network call. It does not expose full node schemas or required properties.

Architectural Topology Projection (4-View Model)

+========================================================================================================+

| [VIEW 1: CALLER RUNTIMES & AGENT ECOSYSTEM] | | Claude Code CLI | Claude Desktop | Cursor IDE / Windsurf | Antigravity / Gemini / Codex | | (JSON-RPC 2.0 Stdio) | (stdio MCP Client) | (Dev Environments) | (Autonomous Orchestrator Swarms) | +===================================================+====================================================+ | v +========================================================================================================+ | [VIEW 2: N8N-MANAGER-MCP CORE ENGINE & MUTATION CHECKS] | | +----------------------------------------------------------------------------------------------------+ | | | Tool Dispatcher (19 Registered MCP Tools: CRUD, Execution Inspect, Backup/Restore, Node Catalog) | | | +----------------------------------------------------------------------------------------------------+ | | | Read-Only Check: persisted setting or N8N_MANAGER_READ_ONLY=1 process ceiling | | | | Input Bounds and Backup-Path Checks (scope limited to the implemented handlers) | | | | Multi-Instance Routing: configured profiles and endpoints | | | | Bundled Offline Node Catalog: Common Node Types & Descriptions (INV-NODE-09) | | | +----------------------------------------------------------------------------------------------------+ | +===================================================+====================================================+ | v +========================================================================================================+ | [VIEW 3: RUNTIME PERSISTENCE, BACKUP SNAPSHOTS & LOCAL AUDIT LOG] | | +------------------------------------+----------------------------------+----------------------------+ | | | Conditional Workflow Snapshots | Local Append-Only Audit Log | Multi-Server Config Store | | | | ~/.n8n-manager-mcp/backups/ | ~/.n8n-manager-mcp/audit.log | ~/.n8n-manager-mcp/ | | | | ({server}/{id}-{timestamp}-{reason}.json) | (Timestamped JSON entries) | (servers.json; POSIX 0600 requested) | | | +------------------------------------+----------------------------------+----------------------------+ | +===================================================+====================================================+ | v +========================================================================================================+ | [VIEW 4: STDIO TRANSPORT, CONFIGURED ENDPOINTS & LAUNCHER PRIVILEGES] | | Inherits launcher process privileges | Configured n8n/manager requests; interactive update check may run | | No MCP listening port (stdio transport) | Published security policy and reporting contacts | +========================================================================================================+

---

Dual Mermaid Diagrams

Component Architecture

flowchart TD

Client["AI Client (Claude Code / Desktop / Cursor / Windsurf)"] -->|"MCP Stdio Protocol (JSON-RPC 2.0)"| Router["Tool Router (19 Tools)"] subgraph MCPServer["n8n Manager MCP Server (Local Stdio Process)"] Router --> Safety["Mutation Checks (Read-Only Gate & Backup-Path Checks)"] Safety --> Backup["Conditional Pre-Mutation Snapshot"] Safety --> MultiServer["Multi-Server Manager"] Safety --> Catalog["Offline Node Catalog (n8n_describe_nodes)"] Router --> Audit["Local Audit Append"] end MultiServer -->|"REST API (API Key / Auth Header)"| LocalInst["Configured n8n Instance (local or remote URL)"] MultiServer -->|"REST API (HTTPS / Token)"| CloudInst["Remote / Cloud n8n Instance"] Backup --> BackupFS[("Backups (~/.n8n-manager-mcp/backups/)")] Audit --> AuditFS[("Audit Log (~/.n8n-manager-mcp/audit.log)")]

Safe Workflow Mutation Lifecycle

These diagrams show the intended operation order. Snapshots are attempted only when backup_before_mutations is enabled (default: true); if that attempt fails, the following n8n mutation request is not sent. Audit append errors propagate and can follow a successful remote mutation.

sequenceDiagram

autonumber actor AI as AI Assistant (Claude / Cursor) participant MCP as n8n-manager-mcp Router participant Safety