MCP server for n8n workflow management -- view, create, sync and manage workflows via AI.
Part of the ellmos-ai family and the open-bricks umbrella.
[!NOTE] For AI Assistants & LLMs: An
llms.txtindex 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.
| Nr | Section | Highlights |
|---|---|---|
| 01 | 📐 System Architecture & Topology (#system-architecture) | Local stdio transport, multi-server routing, and safety middleware |
| 02 | 📊 Dual Mermaid Diagrams (#dual-mermaid-diagrams) | Component Architecture flowchart TD & Safe Mutation Lifecycle sequence diagram |
| 03 | 🌐 Directory Status & Registries (#directory-status) | Official listings on npm, Glama, PulseMCP, and Enterprise DNA |
| 04 | 🎯 Target Personas & Discoverability (#target-personas--discoverability) | Persona mapping [PERSONA-01] to [PERSONA-04] and High-Intent SEO queries |
| 05 | ⚖️ Comparative Matrix & Alternatives (#comparative-matrix--alternatives) | 10-dimension evaluation vs raw REST API, shell CLI, browser UI, and cloud SaaS |
| 06 | 🛡️ Core Capabilities & Safety Invariants (#core-capabilities--safety-invariants) | 10 formal invariants (INV-LOCAL-01 to INV-SLA-10), read-only gates, audit logs |
| 07 | ✨ Key Features (#features) | Direct REST integration, multi-server routing, backup snapshots, node catalog |
| 08 | ⚙️ Client Installation (#installation) | One-command setup for Claude Code, Claude Desktop, Cursor, and Windsurf |
| 09 | 🚀 Quick Start (#quick-start) | Step-by-step workflow creation, execution inspection, and server switching |
| 10 | 🛠️ Available Tools (19 Tools) (#available-tools) | Complete MCP tool reference across CRUD, executions, backups, and nodes |
| 11 | 🔗 Optional: n8n-workflow-manager Seam (#optional-n8n-workflow-manager-seam) | Decision tracking and change history integration with paired manager service |
| 12 | 🔒 Configuration & Safety Defaults (#configuration) | Environment variables, local backup root, and strict monotonic constraints |
| 13 | 🧪 Development & Testing (#development) | Multi-OS Vitest test suite, smoke runner, and offline node catalog tests |
| 14 | 🧱 ellmos-ai Ecosystem (#ellmos-ai-ecosystem) | Sibling MCP servers, BACH agent OS, and open-bricks desktop software suites |
| 15 | 📜 Third-Party Licenses & Transparency (#third-party-licenses--transparency) | 100% permissive open-source dependencies (MIT, BSD, Apache-2.0) |
| 16 | 📈 Marketing & Personas Log (#marketing--personas-log) | Comprehensive positioning log, keyword matrix, and 3-phase roadmap |
| 17 | 📝 Changelog (#changelog) | Complete release notes, security hardenings, and discoverability history |
| 18 | ⚖️ Liability / Haftung (#haftung--liability) | Statutory open-source donation notice under §§ 516 ff. BGB, MIT disclaimer, 48h SLA |
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.
RunAsInvoker) as a dedicated Node.js child process communicating via standard input/output (stdio) using JSON-RPC 2.0.n8n_describe_nodes) without incurring API latency or network calls.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)")]
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
n8n-manager-mcpellmos-ai/n8n-manager-mcpellmos-ai-n8n-managerserver.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.n8n MCP server, n8n workflow management MCP, AI assistant n8n workflows, and ellmos-ai n8n-manager-mcp.| Persona | Core Needs | Pain Points Solved | Target Discovery Terms |
|---|---|---|---|
| [PERSONA-01] Autonomous AI Agents & Swarms | Non-destructive workflow manipulation, pre-mutation snapshots, deterministic receipts | LLM hallucination breaking active production workflows; inability to inspect node connections offline | n8n mcp server, ai agent n8n workflow management, claude code n8n automation |
| [PERSONA-02] DevOps & Multi-Environment Engineers | Safe multi-server routing, export/import synchronization across stages | Manual JSON export friction; staging-to-production drift; unversioned workflow copies | n8n multi-server mcp, sync n8n workflows staging prod, n8n workflow export import mcp |
| [PERSONA-03] SecOps, Compliance & Risk Teams | Monotonic read-only locks, local audit trail, zero external data leakage | Unregulated agent mutations; unvetted API calls; loss of forensic mutation history | safe n8n mcp server, read-only n8n automation, audit log n8n ai integration |
| [PERSONA-04] Ecosystem Builders & Tool Integrators | Standardized MCP schemas, validated manifests, reliable TypeScript SDK seam | Schema mismatch across MCP directories; missing regression and contract test suites | modelcontextprotocol n8n, glama n8n-manager-mcp, smithery n8n workflow |
n8n mcp server claude codeai assistant n8n workflow managementlocal-first n8n mcp stdiosafe n8n automated workflow mutationn8n multi-server workflow sync mcpn8n describe nodes offline catalogzero-egress n8n agent automationmodelcontextprotocol n8n typescript| Dimension | n8n-manager-mcp | Direct n8n REST API | Standard Agent Shell | Manual n8n Web UI | Generic Cloud SaaS |
|---|---|---|---|---|---|
| Primary Interface | Native MCP Stdio (JSON-RPC) | Raw HTTP REST (Curl/Axios) | Ad-hoc CLI / Bash Scripts | Interactive Web Canvas | Proprietary Web Portal |
| Safety Guardrails | Monotonic Read-Only Gate (N8N_MANAGER_READ_ONLY=1) | None (Unchecked API execution) | Shell exit code heuristics | Human confirmation modals | Remote vendor RBAC |
| Mutation Backups | Automated Pre-Mutation JSON Snapshots (INV-BACK-03) | None (Overwrites live instance) | None (Script dependent) | None (Live canvas modifications) | Vendor-dependent snapshots |
| Rollback Facility | 1-Click n8n_restore_workflow from Local Disk | Manual JSON reconstruction via POST | Manual script rollback logic | Manual node rebuilding on canvas | Vendor rollback UI (Paywalled) |
| Forensic Audit Log | Append-Only Structured audit.log (INV-AUDIT-04) | Generic webserver access logs | Ephemeral terminal stdout | Canvas execution logs only | Cloud vendor log retention |
| Node Introspection | Built-in Offline Catalog (n8n_describe_nodes) | Manual online documentation | Guesswork & parameter trials | Visual palette browsing | Online API documentation |
| Multi-Server Isolation | Isolated Stored Profiles (servers.json) | Manual token switching in scripts | Shell history token exposure | Multi-tab credential clutter | Cloud workspace switching |
| Privacy & Zero-Egress | 100% Local Stdio Transport, Zero Telemetry | Direct HTTP client traffic | Local shell execution | Browser telemetry & analytics | Remote third-party hosting |
| Workflow Migration | Built-in n8n_export_workflow & n8n_import_workflow | Custom Python/Curl ETL scripts | Complex bash/jq pipelines | Download / Upload JSON dialog | Cloud enterprise paywall |
| License & Audited Security | 100% Permissive MIT (Audited, 48h Security SLA) | Fair-Code (n8n source available) | Mixed / Ad-hoc licenses | Commercial / Fair-Code | Closed Proprietary SaaS |
| Invariant ID | Capability / Invariant | Technical Guarantee | User Benefit |
|---|---|---|---|
INV-LOCAL-01 | 100% Local-First & Zero-Egress | MCP Stdio transport; binds only to 127.0.0.1 by default; no external telemetry | Complete privacy; no workflow logic or credentials ever leave your host |
INV-READ-02 | Monotonic Read-Only Enforcement | N8N_MANAGER_READ_ONLY=1 establishes a process-level ceiling immune to tool override | Provable air-gapping against accidental workflow deletions or alterations |
INV-BACK-03 | Automated Pre-Mutation Backups | Full workflow JSON snapshots stored under ~/.n8n-manager-mcp/backups/ before mutate/delete | Instant 1-click rollback via n8n_restore_workflow upon unwanted modifications |
INV-AUDIT-04 | Local Audit Trail | Append-only structured JSON log in ~/.n8n-manager-mcp/audit.log | Complete forensic visibility over all agent actions and execution outcomes |
INV-SRV-05 | Multi-Server & Isolated Credentials | Encrypted/isolated server configs in servers.json; API key whitespace validation | Seamless cross-instance workflow migration between staging and production |
INV-TRAV-06 | Strict Input & Path Traversal Guard | Bounded numeric limits (1..1000), connection indices (0..1000), path escape rejection | Immune to directory traversal, prototype pollution, and malformed payload crashes |
INV-PRIV-07 | Non-Elevation & User-Space Security | Operates strictly as unprivileged user process | Zero root/administrator privilege requirements for local or CI execution |
INV-SEAM-08 | Opt-In Decision History Seam | Clean adapter to n8n-workflow-manager via N8N_MCP_MANAGER_URL; explicit fail-fast | Bridges human decision logs and versioning without corrupting standard MCP mode |
INV-NODE-09 | Built-in Node Catalog & Introspection | Comprehensive offline catalog for triggers, actions, logic, transform, and AI nodes | LLMs formulate valid node connections without trial-and-error network calls |
INV-SLA-10 | Multi-Node CI & 48h Security SLA | Automated GitHub Actions CI across Node.js 20, 22 with Concurrency cancellation; 48h response / 5d triage SLA | Guaranteed cross-platform stability, verified security responsiveness, and regression-free distribution |
Add to claude_desktop_config.json:
{
"mcpServers": {
"n8n-manager": {
"command": "npx",
"args": ["-y", "n8n-manager-mcp"]
}
}
}
claude mcp add --scope user n8n-manager npx -y n8n-manager-mcp
npm install -g n8n-manager-mcp
After installation, use these commands in your AI assistant:
Add your n8n server:
"Add my n8n server at http://localhost:5678 with API key abc123"
List workflows:
"Show me all workflows on my n8n server"
Create a workflow:
"Create an n8n workflow that triggers on a webhook, fetches data from an API, and sends a Slack message"
Check executions:
"Show me the last 10 workflow executions"
| Tool | Description |
|---|---|
n8n_list_workflows | List all workflows on a server |
n8n_get_workflow | Get workflow details (nodes, connections) |
n8n_create_workflow | Create a new workflow from nodes + connections |
n8n_update_workflow | Update an existing workflow |
n8n_delete_workflow | Delete a workflow |
n8n_activate_workflow | Activate or deactivate a workflow |
n8n_list_executions | List recent executions with status |
n8n_export_workflow | Export workflow as importable JSON |
n8n_import_workflow | Import workflow JSON onto a server |
n8n_safety_status | Show local safety settings, backup directory, and audit log path |
n8n_set_safety_mode | Toggle read-only mode, backup-before-mutation, and audit logging |
n8n_list_backups | List local workflow backups created before mutations |
n8n_restore_workflow | Restore a workflow from a local backup |
n8n_add_server | Add/update n8n server connection |
n8n_list_servers | List configured servers |
n8n_ping_server | Test server connection |
n8n_remove_server | Remove a server |
n8n_describe_nodes | Browse available n8n node types |
n8n_manager_history | Read version history, recorded decisions, and sync history from an optional n8n-workflow-manager (opt-in, read-only) |
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:
N8N_MCP_MANAGER_URL, nothing changes — every tool talks to n8n directly, as before.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.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.
Server connections and safety settings are stored in ~/.n8n-manager-mcp/servers.json.
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.~/.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.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
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 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, 22, and 24. 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 calls the safe n8n_describe_nodes catalog tool without requiring n8n credentials.
MIT
This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.
| Server | Tools | Focus | npm |
|---|---|---|---|
| FileCommander | 46 | Filesystem, process management, interactive sessions, cloud-lock-safe operations | ellmos-filecommander-mcp |
| CodeCommander | 22 | Code analysis, JSON repair, imports, diffs, regex | ellmos-codecommander-mcp |
| Clatcher | 12 | File repair, format conversion, batch operations | ellmos-clatcher-mcp |
| n8n Manager | 19 | n8n workflow management via AI assistants | n8n-manager-mcp |
| ControlCenter | 20 | MCP stack discovery, profile management, control plane | ellmos-controlcenter-mcp |
| Homebase | 45 | Local-first LLM memory, knowledge, state, routing, swarm orchestration | ellmos-homebase-mcp (alpha) |
| ServerCommander | 8 | Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics | ellmos-servercommander-mcp (alpha) |
| Blender Use | 3 | Headless Blender asset QA and FBX reimport verification | ellmos-blender-use-mcp (alpha) |
| Open Compute | 10 | Model-agnostic computer use: capture, safety-gated actions, Windows UIA | open-compute-mcp (alpha) |
| Project | Description |
|---|---|
| BACH | Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory |
| open-compute | Model-agnostic computer-use core powering Open Compute MCP |
| clutch | Provider-neutral LLM orchestration with auto-routing and budget tracking |
| rinnsal | Lightweight agent memory, connectors, and automation infrastructure |
| ellmos-stack | Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest) |
| MarbleRun | Autonomous agent chain framework for Claude Code |
| gardener | Minimalist database-driven LLM OS prototype (4 functions, 1 table) |
| ellmos-tests | Testing framework for LLM operating systems (7 dimensions) |
Our partner organization open-bricks and sister suites bundle AI-native desktop applications and developer utilities:
| Repository | Org / Suite | Focus & Functionality |
|---|---|---|
| ProFiler | file-bricks | Advanced file and asset management workbench with duplicate detection |
| ExplorerPro | file-bricks | Tabbed, filterable file manager with smart batch processing |
| WinStorePackager | file-bricks | MSIX packaging and Windows Store release preparation |
| DokuZen | doc-bricks | Offline Markdown editor, live preview, and document structuring workbench |
| PDFtoPDFocr | doc-bricks | Offline OCR pipeline converting scanned PDF documents to searchable PDFs |
| USR_PDFunlock | doc-bricks | Birthday/date password recovery tool for protected PDF archives |
| UniversalInvoiceMail | doc-bricks | Automated invoice extraction and email processing |
| CleanMarkdown | doc-bricks | Lossless formatting and typography cleanup for technical markdown |
| safe-start-for-codex | dev-bricks | Fast, reliable agent bootstrap and environment check runner |
| automation-master | dev-bricks | Central multi-host automation orchestrator and task monitor |
| DevCenter | dev-bricks | Unified developer workspace dashboard for local tool chains |
| CodeBox | dev-bricks | Sandboxed multi-language tool execution environment |
| githubbot | dev-bricks | Automated multi-org repository maintenance and discoverability engine |
| swarm-ai | ellmos-ai | Distributed multi-agent swarming framework with stigmergic coordination |
| ellmos-core | ellmos-ai | Enterprise AI agent backend, hybrid RAG, and multi-tenant security |
| open-bricks | open-bricks | Umbrella portal and catalog across all local-first AI software products |
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:
| Dependency | Type | Version | License | Verification Status |
|---|---|---|---|---|
@modelcontextprotocol/sdk | Runtime (Direct) | ^1.29.0 | MIT | Permissive / Audited |
zod | Runtime (Direct) | ^3.23.8 | MIT | Permissive / Audited |
update-notifier | Runtime (Direct) | ^7.3.1 | BSD-2-Clause | Permissive / Audited |
typescript | Dev / Compiler | ^5.3.3 | Apache-2.0 | Permissive / Audited |
vitest | Dev / Test Runner | ^4.1.11 | MIT | Permissive / Audited |
@types/node | Dev / Type Definitions | ^20.11.0 | MIT | Permissive / Audited |
THIRD_PARTY_LICENSES.md.For marketing positioning, target persona definitions, governance invariant mappings, and the 3-phase discoverability roadmap, see MARKETING-LOG.txt.
See CHANGELOG.md for detailed version history, release notes, and past migration milestones.
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.
As codified in SECURITY.md, we maintain a strict binding security policy:
INV-SLA-10).security@open-bricks.orgsecurity@ellmos.ailukas@open-bricks.orgSource-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y n8n-manager-mcpMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-ellmos-ai-n8n-manager-mcp": {
"command": "npx",
"args": [
"-y",
"n8n-manager-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencen8n-manager-mcpnpmn8n Manager MCP works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.