MCP server for n8n workflow management -- view, create, sync and manage workflows via AI.
n8n Manager MCP Server (io.github.ellmos-ai/n8n-manager-mcp)
MCP server for n8n workflow management that supports viewing, creating, syncing, and managing workflows via AI. It is published as n8n-manager-mcp and is associated with the ellmos-ai GitHub family and open-bricks umbrella. The project targets the Model Context Protocol ecosystem.
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.
Statutory open-source donation notice under §§ 516 ff. BGB, MIT disclaimer, 48h SLA
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.
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.
"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"
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
bash
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.
bash
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.
Contributing & Development Workflow
Contributions are welcome! Please review CONTRIBUTING.md for full guidelines, including:
10 Governance & Runtime Invariants (INV-LOCAL-01 to INV-SLA-10): 100% Local-First, Zero-Egress, 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 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.
Optional Windows tool for checking orphaned MCP processes. n8n Manager is a configured candidate when launched through the supported node_modules/n8n-manager-mcp/dist/index.js entrypoint; all additional process and apply checks still apply
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.
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.
