n8n Manager MCP

n8n Manager MCP Server

🇩🇪 Deutsche Version

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

[npm] [Tests] [MCP Tools] [Node.js] [Safety] [Security] [Third-Party] [Level 1 SBOM: Plain Text] [Attribution: NOTICE] [Verified] [Last-Checked] [License: MIT] [LLM Ready] [Ecosystem: ellmos--ai] [Umbrella: open--bricks]

[!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 purely in user space (RunAsInvoker) as a dedicated Node.js child process communicating via standard input/output (stdio) using JSON-RPC 2.0.
• Fail-Closed Safety Middleware: Every mutation tool call passes through an immutable safety gate before contacting n8n APIs or touching the filesystem.
• Multi-Instance Router: Seamlessly targets independent n8n instances (development, staging, production) with isolated API credentials and atomic configuration persistence.
• Offline Node Catalog: Provides instantaneous node schema introspection (n8n_describe_nodes) without incurring API latency or network calls.

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 & SAFETY ARBITRATION]                                             || +----------------------------------------------------------------------------------------------------+ || | Tool Dispatcher (19 Registered MCP Tools: CRUD, Execution Inspect, Backup/Restore, Node Catalog)   | || +----------------------------------------------------------------------------------------------------+ || | Fail-Closed Safety Filter: N8N_MANAGER_READ_ONLY Enforcement (INV-READ-02)                          | || | Input Validation & Sanitization: Zod Schema Numeric Bounds & Path Traversal Guards (INV-TRAV-06)   | || | Multi-Instance Routing Engine: Development / Staging / Production Credentials Isolation (INV-SRV-05)| || | Bundled Offline Node Catalog: In-Memory Node Schemas & Parameter Introspection (INV-NODE-09)        | || +----------------------------------------------------------------------------------------------------+ |+===================================================+====================================================+                                                    |                                                    v+========================================================================================================+| [VIEW 3: RUNTIME PERSISTENCE, BACKUP SNAPSHOTS & LOCAL AUDIT WAL]                                      || +------------------------------------+----------------------------------+----------------------------+ || | Pre-Mutation Workflow Snapshots    | Append-Only Local Audit Trail    | Multi-Server Config Store  | || | ~/.n8n-manager-mcp/backups/        | ~/.n8n-manager-mcp/audit.log     | ~/.n8n-manager-mcp/        | || | ({server}/{id}-{timestamp}.json)   | (Forensic Timestamped Log)       | (servers.json, POSIX 0600) | || +------------------------------------+----------------------------------+----------------------------+ |+===================================================+====================================================+                                                    |                                                    v+========================================================================================================+| [VIEW 4: DEFENSE PERIMETER, LOCAL STDIO & RUNASINVOKER]                                                || Standard User Mode (RunAsInvoker: Non-Elevation INV-PRIV-07) | Zero Outbound Telemetry / Ad Tracking  || No MCP listening port (stdio transport INV-LOCAL-01)       | SLA & Vulnerability Protocol (INV-SLA-10) |+========================================================================================================+

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["Safety Layer (Read-Only Gate & Traversal Guard)"]        Safety --> Backup["Pre-Mutation Snapshot Engine"]        Safety --> MultiServer["Multi-Server Manager"]        Safety --> Catalog["Offline Node Catalog (n8n_describe_nodes)"]        Backup --> Audit["Append-Only Audit Logger"]    end    MultiServer -->|"REST API (API Key / Auth Header)"| LocalInst["Local n8n Instance (127.0.0.1:5678)"]    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

sequenceDiagram    autonumber    actor AI as AI Assistant (Claude / Cursor)    participant MCP as n8n-manager-mcp Router    participant Safety as Safety & Read-Only Gate    participant Snapshot as Backup Engine    participant Store as Local Storage (~/.n8n-manager-mcp)    participant N8N as n8n REST API Instance    participant Audit as Forensic Audit Logger
    AI->>MCP: Call Mutation Tool (n8n_update_workflow / n8n_delete_workflow)    MCP->>Safety: Check N8N_MANAGER_READ_ONLY    alt Read-Only Active (INV-READ-02)        Safety-->>AI: Blocked: Read-only mode active (Fail-Closed)        Safety->>Audit: Record blocked mutation attempt    else Mutation Permitted        Safety->>Snapshot: Trigger Pre-Mutation Snapshot (INV-BACK-03)        Snapshot->>N8N: GET /workflows/{id} (Fetch current state)        N8N-->>Snapshot: Current Workflow JSON        Snapshot->>Store: Save timestamped backup (~/backups/{server}/{id}-{timestamp}.json)        Snapshot-->>Safety: Backup verified & path resolved        Safety->>N8N: Execute Mutation (PUT / DELETE / PATCH)        N8N-->>Safety: Mutation Response (200 OK / Updated ID)        Safety->>Audit: Append structured forensic receipt (INV-AUDIT-04)        Safety-->>AI: Success response with backup path & rollback receipt    end

Multi-Server Workflow Migration & Staging Synchronization Lifecycle

sequenceDiagram    autonumber    actor AI as AI Assistant (Claude / Cursor)    participant MCP as n8n-manager-mcp Router    participant Staging as Staging n8n Instance    participant Store as Local Storage (~/.n8n-manager-mcp)    participant Prod as Production n8n Instance    participant Audit as Forensic Audit Logger
    Note over AI,MCP: Phase 1: Export & Introspection from Staging    AI->>MCP: n8n_export_workflow(serverId, workflowId)    MCP->>Staging: GET /workflows/42 (Fetch Staging Workflow)    Staging-->>MCP: Workflow JSON Payload    MCP-->>AI: Exported Workflow JSON & Node Topology
    Note over AI,MCP: Phase 2: Offline Node Compatibility Verification    AI->>MCP: n8n_describe_nodes(nodes)    MCP-->>AI: Bundled Node Schema & Required Properties (INV-NODE-09)
    Note over AI,MCP: Phase 3: Safe Promotion & Pre-Mutation Snapshot    AI->>MCP: n8n_import_workflow(serverId, workflow, activate)    MCP->>Store: Create Safety Snapshot (~/backups/production/42-ts.json, INV-BACK-03)    MCP->>Prod: POST /workflows (Create/Promote Workflow)    Prod-->>MCP: Created Workflow (id: 108, active: false)    MCP->>Audit: Append Forensic Receipt (INV-AUDIT-04)    MCP-->>AI: Promotion Success Receipt & Rollback Handle

Directory Status

• npm package: published as n8n-manager-mcp
• Glama listing: public directory page for the ellmos-ai repo
• Enterprise DNA directory: additional public directory entry for ellmos-ai/n8n-manager-mcp
• PulseMCP listing: indexed as ellmos-ai-n8n-manager
• MCP namespace status: this repo contains server.json and mcpName metadata for io.github.ellmos-ai/n8n-manager-mcp; some ecosystem directories still expose the legacy io.github.lukisch/n8n-manager-mcp name until their indexes refresh.
• Search context: best matched by n8n MCP server, n8n workflow management MCP, AI assistant n8n workflows, and ellmos-ai n8n-manager-mcp.

Target Personas & Discoverability

High-Intent Search Queries

• n8n mcp server claude code
• ai assistant n8n workflow management
• local-first n8n mcp stdio
• safe n8n automated workflow mutation
• n8n multi-server workflow sync mcp
• n8n describe nodes offline catalog
• local-stdio n8n agent automation without telemetry
• modelcontextprotocol n8n typescript

Comparative Matrix & Alternatives

Core Capabilities & Safety Invariants

Features

• 19 Tools for complete n8n workflow management
• List, create, update, delete, and activate/deactivate workflows
• Safety controls: read-only mode, backup-before-delete/update, local restore, and audit log
• Multi-server support (connect to multiple n8n instances)
• Export/Import workflows between servers
• View execution history and status
• Built-in node catalog with descriptions
• Zero dependencies on Python -- connects directly to n8n REST API

Installation

Claude Desktop

Add to claude_desktop_config.json:

{  "mcpServers": {    "n8n-manager": {      "command": "npx",      "args": ["-y", "n8n-manager-mcp"]    }  }}

Claude Code

claude mcp add --scope user n8n-manager npx -y n8n-manager-mcp

Manual

npm install -g n8n-manager-mcp

Quick Start

Natural Language Prompts

After installation, use these prompts directly in your AI assistant:

1. Add your n8n server:

   "Add my n8n server named production at http://localhost:5678 with my API key"

2. List workflows:

   "Show me all workflows on my n8n server"

3. Inspect nodes offline:

   "Describe the HTTP Request and Webhook nodes so we can construct a new workflow"

4. Create a workflow:

   "Create an n8n workflow that triggers on a webhook, fetches data from an API, and sends a Slack message"

5. Check executions:

   "Show me the last 10 workflow executions on production"

6. Promote across environments:

   "Export workflow 42 from staging and import it to production without activating"

End-to-End Developer & Agent Execution Showcase

Below is a step-by-step walkthrough of how an AI assistant (e.g. Claude Code or Cursor) interacts with n8n-manager-mcp across configuration, inspection, pre-mutation snapshotting, and rollback:

1. Multi-Server Registration & Health Check

Configure your n8n endpoints. Passwords and API keys are stored with restricted POSIX file permissions (0600) under ~/.n8n-manager-mcp/servers.json:

// Tool Call: n8n_add_server{  "name": "staging",  "url": "http://127.0.0.1:5678",  "apiKey": "n8n_api_key_staging",  "isDefault": true}

Response Receipt:

{  "success": true,  "server": "staging",  "url": "http://127.0.0.1:5678",  "isDefault": true}

Verify connection reachability without modifying workflows:

// Tool Call: n8n_ping_server{  "name": "staging"}

Response Receipt:

{  "server": "staging",  "status": "online",  "latencyMs": 14}

2. Zero-Latency Offline Node Introspection

Inspect node schemas and connection ports instantaneously from the bundled catalog without making network requests (INV-NODE-09):

// Tool Call: n8n_describe_nodes{  "nodeTypes": ["n8n-nodes-base.webhook", "n8n-nodes-base.httpRequest"]}

Response Receipt:

{  "nodes": [    {      "name": "n8n-nodes-base.webhook",      "displayName": "Webhook",      "description": "Starts the workflow when a webhook request is received",      "inputs": [],      "outputs": ["main"]    },    {      "name": "n8n-nodes-base.httpRequest",      "displayName": "HTTP Request",      "description": "Makes an HTTP request and returns the response",      "inputs": ["main"],      "outputs": ["main"]    }  ]}

3. Safe Workflow Mutation with Automated Snapshot

When updating an existing workflow, n8n-manager-mcp automatically saves a timestamped JSON snapshot before sending changes to the n8n API (INV-BACK-03):

// Tool Call: n8n_update_workflow{  "id": "42",  "workflow": {    "name": "Customer Webhook Ingest [v2]",    "nodes": [ /* updated node graph */ ],    "connections": { /* node wiring */ }  }}

Response Receipt (Pre-Mutation Backup Verified):

{  "success": true,  "id": "42",  "name": "Customer Webhook Ingest [v2]",  "active": true,  "backupPath": "~/.n8n-manager-mcp/backups/staging/42-2026-10-30T04-45-00-000Z.json",  "auditReceipt": "AUDIT-20261030-42-MUTATION-OK"}

4. Instant 1-Click Rollback

If a newly deployed workflow mutation causes unexpected behavior, restore the exact previous state in a single tool call:

// Tool Call: n8n_restore_workflow{  "id": "42",  "backupPath": "~/.n8n-manager-mcp/backups/staging/42-2026-10-30T04-45-00-000Z.json"}

Response Receipt:

{  "success": true,  "id": "42",  "restoredFrom": "~/.n8n-manager-mcp/backups/staging/42-2026-10-30T04-45-00-000Z.json",  "status": "rolled_back"}

5. Fail-Closed Read-Only Protection

To lock the environment against any modifications during security audits, set N8N_MANAGER_READ_ONLY=1. Any mutation call is blocked at process boundary (INV-READ-02):

// Tool Call: n8n_delete_workflow (with N8N_MANAGER_READ_ONLY=1){  "id": "42"}

Response Receipt (Fail-Closed Gate):

{  "error": "Operation rejected: N8N_MANAGER_READ_ONLY mode is active (INV-READ-02). Mutations are prohibited.",  "status": "blocked"}

Available Tools

Optional: n8n-workflow-manager seam

n8n itself keeps no record of why a workflow changed. The sibling project n8n-workflow-manager does: it stores versions, a mandatory decision per mutation, and a sync history in a local database. n8n_manager_history makes that record readable from this MCP server.

The seam is opt-in and read-only:

• Without N8N_MCP_MANAGER_URL, nothing changes — every tool talks to n8n directly, as before.
• With it set (for example http://127.0.0.1:8100), n8n_manager_history reads from the running manager. Omit workflow_id to list the manager's workflows, pass it for full history.
• IDs are manager IDs, not n8n instance IDs. The manager stores that mapping but exposes no route to resolve it, so this server does not guess a translation.
• If the manager is configured but unreachable, the tool fails with an explicit message instead of quietly answering from the n8n instance — that store has no decision history, so a substituted answer would be a different answer.
• n8n_safety_status reports the measured state of the seam (configured, reachable, manager version), not just the environment variable.

Setup: pip install n8n-workflow-manager, then n8n-manager serve (binds 127.0.0.1:8100). The manager API is unauthenticated and loopback-only by design; a non-loopback URL is flagged in n8n_safety_status.

Numeric guardrails are part of the MCP schemas: workflow, execution, and backup list limits are finite positive integers from 1 to 1000 (the existing defaults remain 100, 20, and 20), and workflow connection from_output/ to_input indices are finite non-negative integers from 0 to 1000. Invalid values are rejected before any n8n API, filesystem, or workflow-array access.

Configuration

Server connections and safety settings are stored in ~/.n8n-manager-mcp/servers.json.

API key data flow

Set N8N_MANAGER_API_KEY and N8N_MANAGER_SERVER_URL in the MCP host process environment before starting the server. Use your client's sensitive user configuration or an OS secret facility when available; check whether your client writes environment values to a plaintext configuration file. N8N_MANAGER_SERVER_URL must match the URL passed to n8n_add_server (trailing slashes are normalized). Do not include an API key in a chat prompt or tool argument.

n8n_add_server reads the key from the host environment, validates it, and saves it with the server profile in local servers.json. The file is plaintext, not encrypted; new files request mode 0600 on POSIX, while Windows access follows the directory ACL. The MCP tool schema, outgoing tool results, and server list contain no configured key value. API calls send the key in the X-N8N-API-KEY header to the configured n8n URL; redirects are not followed. Use HTTPS for remote n8n servers. Echoed keys in successful and failed upstream responses are redacted at the MCP output and audit boundaries, including JSON object keys and workflow IDs.

Existing servers.json profiles keep working. Updating a profile at the same URL preserves its stored key even when an environment key is present. To rotate a key or change a profile URL, set the new key and matching URL in the host environment, restart the MCP server, then call n8n_add_server with rotate_key: true. A URL change without rotation is refused. For multiple servers, configure and add each server with its own environment key/URL pair, restarting the MCP process between pairs; already stored keys are not silently replaced. After onboarding, the environment pair can be removed on restart because the key remains in the local profile. Remove any old prompts or client calls that supplied api_key as a tool argument.

Safety defaults:

• backup_before_mutations: true saves workflow JSON before update, delete, activate/deactivate, and overwrite-restore operations.
• audit_log: true appends mutation outcomes to ~/.n8n-manager-mcp/audit.log.
• read_only: false can be enabled with n8n_set_safety_mode or N8N_MANAGER_READ_ONLY=1. The environment flag is an enforcement ceiling: while it is enabled, persisted settings and n8n_set_safety_mode cannot turn read-only mode off.
• Backups are stored under ~/.n8n-manager-mcp/backups/ and can be listed/restored with the backup tools. Server/workflow names are reduced to safe single path segments; reserved names, separators, traversal, and symlink/reparse escapes cannot leave that root, and listing exposes only regular .json backups.
• n8n_add_server validates server connection input before saving: URLs must be http or https base URLs without embedded credentials, query strings, or fragments, and API keys must not contain whitespace.
• n8n_add_server default semantics are explicit: the first server becomes default; an update without is_default preserves the existing flag; true promotes the server; false intentionally removes its flag, after which default lookup falls back to the first configured server.

Development

npm installnpm run build    # One-time buildnpm run dev      # Watch modenpm start        # Start servernpm test         # Run test suite (vitest)npm run smoke    # Start the built MCP server and verify tool discovery

Testing

The test suite covers URL building, server input validation, server management, safety settings, backup path handling, workflow JSON construction, export/import validation, i18n language packs, repository hygiene, and error handling. The manager seam is tested against a local stub HTTP server, including its refusal to fall back to a direct n8n query.

npm test              # Run all testsnpx vitest run        # Same as abovenpx vitest --watch    # Watch modenpm run smoke         # Manual stdio MCP smoke test (requires npm run build first)

The current verification record covers Windows locally and Ubuntu Linux in GitHub Actions; GitHub Actions runs build, test, and npm package checks on Node.js 20 and 22. The commit-specific local record is kept in CHANGELOG.md. The smoke runner starts dist/index.js through the MCP SDK client, verifies all 19 tool registrations and secret-free server setup with synthetic credentials, and uses loopback stubs to test key redaction and redirect refusal. It does not contact a real n8n server.

Contributing & Development Workflow

Contributions are welcome! Please review CONTRIBUTING.md and our CODE_OF_CONDUCT.md for full guidelines, including:

• 10 Governance & Runtime Invariants (INV-LOCAL-01 to INV-SLA-10): local MCP transport without telemetry, monotonic read-only gates, and automated backups.
• Unprivileged User Mode (RunAsInvoker): Zero administrative elevation requested.
• Plan D Workflow: Development strictly against canonical local clones and GitHub origin/main.
• 48h Security Response SLA: Coordinated vulnerability disclosure via [email protected] and [email protected].

Related

• n8n-workflow-manager — the state & history layer for humans (Web UI + REST API, Python): per-workflow change history and decision log, visual graph viewer, multi-server sync. Designed as a pair with this MCP server — the MCP is the AI action layer (create/update/delete/activate), the manager is where you review, document, and roll back. Memory & context (roadmap): an MCP server alone can't guarantee an agent checks prior context before a destructive change — that enforcement belongs in the manager (client-agnostic), with conversational context optionally from a pull-based history index like ctx (Apache-2.0). Planned: a shared history/decision store + a check-history-before-mutating guard.
• n8n -- The workflow automation platform

License

MIT

ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

MCP Server Family

AI Infrastructure

Desktop Software & Sibling Tools

Our partner organization open-bricks and sister suites bundle AI-native desktop applications and developer utilities:

Third-Party Licenses & Transparency

This project is licensed under the MIT License with attribution declared in NOTICE. To guarantee complete supply chain integrity and compliance in enterprise and autonomous agent environments, all dependencies are continuously audited:

• Zero Copyleft / AGPL: Contains no viral copyleft or unreviewed commercial dependencies.
• Zero External Telemetry: Emits no network beacons, analytics payloads, or external phone-home pings.
• Detailed Open-Source Inventory: Complete attribution notices, license texts, and transitive dependency analyses are available in THIRD_PARTY_LICENSES.md.
• Level 1 SBOM Plain-Text Companion: Complete machine-readable audit trail, non-elevation certification, and license companion available in THIRD_PARTY_LICENSES.txt.

Marketing & Personas Log

For marketing positioning, target persona definitions, governance invariant mappings, and the 3-phase discoverability roadmap, see MARKETING-LOG.txt.

Changelog

See CHANGELOG.md for detailed version history, release notes, and past migration milestones.

Haftung / Liability

Statutory Notice & Liability Disclaimer (§ 521 BGB)

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gilt der Haftungsausschluss der MIT-Lizenz.

Nutzung auf eigenes Risiko. Keine Wartungszusage, keine Verfügbarkeitsgarantie, keine Gewähr für Fehlerfreiheit oder Eignung für einen bestimmten Zweck.

This project is an unpaid open-source donation under the MIT License. Liability is limited to intent and gross negligence (§ 521 German Civil Code). Use at your own risk. No warranty, no maintenance guarantee, no fitness-for-purpose assumed.

Security Response SLA & Vulnerability Reporting

As codified in SECURITY.md, we maintain a strict binding security policy:

• Initial Response SLA: Guaranteed within 48 hours (INV-SLA-10).
• Triage Commitment: Vulnerability assessment completed within 5 business days.
• Remediation SLA: Coordinated security patches delivered within 30 calendar days.
• Direct Contact Endpoints:
  • [email protected]
  • [email protected]
  • [email protected]