n8n Manager MCP

n8n Manager MCP Server

🇩🇪 Deutsche Version

Part of the ellmos-ai family and 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

• Overview & Architecture
• Directory Status
• Core Capabilities & Safety Invariants
• Features
• Installation
• Quick Start
• Available Tools (19 Tools)
• Optional: n8n-workflow-manager Seam
• Configuration & Safety Defaults
• Development & Testing
• Related Projects
• ellmos-ai Ecosystem
• Liability & License

System Architecture

graph TD
    A["AI Client (Claude / Cursor / Windsurf)"] -->|MCP Stdio Protocol| B["n8n Manager MCP Server"]
    subgraph "n8n Manager MCP Server"
        B --> C["Tool Router (19 Tools)"]
        C --> D["Safety Layer (Read-Only / Backups / Audit)"]
        C --> E["Multi-Server Manager"]
    end
    E -->|REST API (API Key / Basic Auth)| F["n8n Instance 1 (Local)"]
    E -->|REST API (API Key / Basic Auth)| G["n8n Instance 2 (Cloud / Remote)"]
    D --> H[("Local Store (~/.n8n-manager-mcp/)")]

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.

Core Capabilities & Safety Invariants

Capability / Invariant	Technical Guarantee	User Benefit
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
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
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
Local Audit Trail	Append-only structured JSON log in ~/.n8n-manager-mcp/audit.log	Complete forensic visibility over all agent actions and execution outcomes
Multi-Server & Isolated Credentials	Encrypted/isolated server configs in servers.json; API key whitespace validation	Seamless cross-instance workflow migration between staging and production
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
Non-Elevation & User-Space Security	Operates strictly as unprivileged user process	Zero root/administrator privilege requirements for local or CI execution
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
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
Multi-Node & Multi-OS CI Matrix	Automated GitHub Actions CI across Node.js 20, 22 with Concurrency cancellation	Guaranteed cross-platform stability and regression-free distribution

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

After installation, use these commands in your AI assistant:

1. Add your n8n server:

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

2. List workflows:

   "Show me all workflows on my n8n server"

3. Create a workflow:

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

4. Check executions:

   "Show me the last 10 workflow executions"

Available Tools

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)

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.

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

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

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)

AI Infrastructure

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)

Desktop Software & Sibling Tools

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

Haftung / Liability

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.