N8n Manager MCP README

n8n Manager MCP Server

🇬🇧 English | 🇩🇪 Deutsch | 🇪🇸 Español | 🇯🇵 日本語 | 🇷🇺 Русский | 🇫🇷 Français | 🇨🇳 简体中文 | 🇮🇳 हिन्दी | العربية | বাংলা | Português

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 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 Local Audit Logger

    AI->>MCP: Call n8n_update_workflow or n8n_delete_workflow
    MCP->>Safety: Check read-only enforcement
    alt Read-only active (INV-READ-02)
        opt audit_log enabled (default true)
            Safety->>Audit: Append blocked mutation attempt
        end
        Safety-->>AI: Return text explaining that the mutation is blocked (or an error if audit append fails)
    else Mutation permitted
        opt backup_before_mutations enabled (default true)
            Safety->>Snapshot: Trigger pre-mutation snapshot (INV-BACK-03)
            Snapshot->>N8N: GET /workflows/{id}
            N8N-->>Snapshot: Current workflow JSON
            Snapshot->>Store: Save ~/.n8n-manager-mcp/backups/{server}/{id}-{timestamp}-{reason}.json
            Snapshot-->>Safety: Backup path
        end
        Safety->>N8N: PUT /workflows/{id} or DELETE /workflows/{id}
        N8N-->>Safety: Mutation result
        opt audit_log enabled (default true)
            Safety->>Audit: Append structured outcome to audit log (INV-AUDIT-04)
        end
        Safety-->>AI: Return text; include backup path when a backup was saved
    end

Multi-Server Workflow Migration & Staging Synchronization Lifecycle

The import step creates a new workflow. It does not create a pre-import backup or return a rollback handle.

sequenceDiagram
    autonumber
    actor AI as AI Assistant (Claude / Cursor)
    participant MCP as n8n-manager-mcp Router
    participant Staging as Staging n8n Instance
    participant Prod as Production n8n Instance
    participant Audit as Local Audit Logger

    Note over AI,MCP: Phase 1: Export from staging
    AI->>MCP: n8n_export_workflow(workflow_id=42, server_name=staging)
    MCP->>Staging: GET /workflows/42
    Staging-->>MCP: Workflow JSON
    MCP-->>AI: Cleaned workflow JSON as text

    Note over AI,MCP: Phase 2: Offline node-type catalog
    AI->>MCP: n8n_describe_nodes(category=action)
    MCP-->>AI: Text list of node types and descriptions

    Note over AI,MCP: Phase 3: Import a new inactive copy
    AI->>MCP: n8n_import_workflow(workflow_json=serialized export, server_name=production, activate=false)
    MCP->>Prod: POST /workflows
    Prod-->>MCP: Created workflow JSON with a new ID; inactive
    opt audit_log enabled (default true)
        MCP->>Audit: Append import outcome (INV-AUDIT-04)
    end
    MCP-->>AI: Text response with the new workflow ID; no 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
• n8n MCP stdio with configured server endpoints
• modelcontextprotocol n8n typescript

Project Capabilities & Boundaries

Capabilities & Implementation Boundaries

These reference IDs group implementation areas; they are not external certifications or guarantees.

Features

• 19 Tools for complete n8n workflow management
• List, create, update, delete, and activate/deactivate workflows
• Safety controls: read-only mode, configurable backups for supported mutations (enabled by default), local restore, and configurable audit logging (enabled by default)
• 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 in your AI assistant. Before registering a server, securely configure N8N_MANAGER_API_KEY and the matching N8N_MANAGER_SERVER_URL in the MCP host environment. Do not include the API key in a prompt or tool argument:

1. Add your n8n server:

   "Add an n8n server profile named production at http://localhost:5678 using the already configured host credentials"

2. List workflows:

   "Show me all workflows on my n8n server"

3. Inspect nodes offline:

   "Show the action node types and descriptions from the bundled offline catalog"

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. Import a copy across environments:

   "Export workflow 42 from staging and import a new inactive copy into production"

   Note: n8n_import_workflow creates a new workflow; it does not create a pre-import backup or return a rollback handle. The copy stays inactive unless activation is requested.

End-to-End Developer & Agent Execution Showcase

Below is a step-by-step walkthrough of server configuration, offline catalog lookup, workflow mutation with backup, restore, and read-only behavior. Examples show tool-argument shapes and illustrative MCP text responses.

1. Multi-Server Registration & Health Check

Before registering a new server, configure N8N_MANAGER_API_KEY and a matching N8N_MANAGER_SERVER_URL in the MCP host environment using the client's sensitive settings or an OS secret facility. Never pass the API key in a chat prompt or tool argument. The local server profile stores the key as plaintext; new files request mode 0600 on POSIX, while Windows access follows the directory ACL.

Call n8n_add_server:

{
  "name": "staging",
  "url": "http://127.0.0.1:5678",
  "is_default": true
}

Illustrative MCP text response (the server name and URL follow the request):

Server "staging" added (http://127.0.0.1:5678). Set as default.

Call n8n_ping_server:

{
  "server_name": "staging"
}

Illustrative MCP text response (response time varies):

Server "staging" (http://127.0.0.1:5678) is reachable. Response time: <N>ms

2. Offline Node Catalog

n8n_describe_nodes filters the bundled catalog by category. It returns text descriptions, not full node schemas or a selected list of node names.

Call n8n_describe_nodes:

{
  "category": "action"
}

Illustrative response text:

n8n Node Types (action):

  [ACTION] n8n-nodes-base.httpRequest
    Name: HTTP Request
    Make HTTP requests. Params: url, method, headers, body

  [ACTION] n8n-nodes-base.emailSend
    Name: Send Email
    Send emails via SMTP. Params: fromEmail, toEmail, subject, text

  [ACTION] n8n-nodes-base.slack
    Name: Slack
    Send messages to Slack channels

  [ACTION] n8n-nodes-base.telegram
    Name: Telegram
    Send messages via Telegram bot

  [ACTION] n8n-nodes-base.googleSheets
    Name: Google Sheets
    Read/write Google Sheets data

3. Safe Workflow Update with Automated Snapshot

When backup_before_mutations is enabled (default: true), n8n_update_workflow saves a timestamped snapshot before sending the update to n8n. This example shows the argument shape only: replace the placeholder with the complete, JSON-serialized updated workflow.

Call n8n_update_workflow:

{
  "workflow_id": "42",
  "server_name": "staging",
  "workflow_json": "<complete JSON-serialized updated workflow>"
}

Illustrative MCP text response when the default backup is enabled:

Workflow 42 updated successfully on staging. Backup saved: <backup path>

4. Restore from a Local Backup

To overwrite workflow 42, pass its backup path and target_workflow_id. With backup_before_mutations enabled, the current target is backed up before it is overwritten. Omitting target_workflow_id creates a new workflow instead.

Call n8n_restore_workflow:

{
  "backup_path": "<path returned by n8n_list_backups or a mutation response>",
  "server_name": "staging",
  "target_workflow_id": "42"
}

Illustrative MCP text response when the pre-restore backup is enabled:

Workflow restored (overwritten) on staging: "Customer Webhook Ingest [v2]" (ID: 42). Pre-restore backup saved: <backup path>

5. Fail-Closed Read-Only Protection

If audit_log is enabled (default: true), a blocked mutation is appended to the audit log; an append error can make the tool call fail. If N8N_MANAGER_READ_ONLY=1 is set in the MCP host environment, it is a monotonic ceiling: n8n_set_safety_mode cannot disable it. Remove the environment variable and restart the MCP server to lift that ceiling. The runtime's generic text below still mentions n8n_set_safety_mode; that suggestion does not apply while the environment ceiling is active.

Call n8n_delete_workflow:

{
  "workflow_id": "42",
  "server_name": "staging"
}

Illustrative runtime text response when read-only mode is active:

Blocked: n8n Manager is in read-only mode. Disable read_only via n8n_set_safety_mode before delete_workflow.

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 binds to loopback by default; its host is configurable. 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 by the MCP input schemas or workflow validation before the corresponding operation proceeds. Configuration loading may access the local filesystem before a mutation check.

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. Backup path segments are sanitized and real-path/symlink checks are used in backup, listing, and restore handling. Listing exposes regular .json backups. These checks are scoped to those operations, not a general filesystem guarantee.
• 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 install
npm run build    # One-time build
npm run dev      # Watch mode
npm start        # Start server
npm 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 tests
npx vitest run        # Same as above
npx vitest --watch    # Watch mode
npm run smoke         # Manual stdio MCP smoke test (requires npm run build first)

The recorded verification 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:

• Implementation areas (INV-LOCAL-01 to INV-SLA-10): stdio transport, read-only mode, configurable backups and audit logging, validation, and the published security policy; see the documented scope and limits above.
• Process privileges: the process inherits the privileges of its launcher and does not request elevation.
• Plan D Workflow: Development strictly against canonical local clones and GitHub origin/main.
• Published security policy: Response, triage, and remediation commitments are listed in SECURITY.md; coordinated disclosure contacts include security@ellmos.ai and security@open-bricks.org.

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. The dependency table below lists selected direct and development dependencies declared for this project. License details are provided in the repository inventory; this table does not claim continuous auditing or certify supply-chain security:

• Network scope: The server sends requests to configured n8n endpoints and, when enabled, the configured manager endpoint. The update notifier may check for updates on interactive TTY startup; the regular non-TTY stdio path skips it. The reviewed application source contains no product-analytics sender.
• Detailed Open-Source Inventory: Complete attribution notices, license texts, and transitive dependency analyses are available in THIRD_PARTY_LICENSES.md.
• Plain-text dependency companion: A text dependency/license inventory is available in THIRD_PARTY_LICENSES.txt; it is not a runtime audit trail or privilege certification.

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 stated in SECURITY.md, the published security policy makes these response, triage, and remediation commitments:

• Initial Response Commitment: The published policy sets an initial response within 48 hours (INV-SLA-10).
• Triage Commitment: The published policy sets vulnerability assessment within 5 business days.
• Remediation Commitment: The published policy sets coordinated security remediation within 30 calendar days after confirmation of a reported vulnerability.
• Direct Contact Endpoints:
  • security@open-bricks.org
  • security@ellmos.ai
  • lukas@open-bricks.org

These are policy commitments; this document does not report measured response performance.