n8n-mcp-cli
Provides production-safe validation, health scoring, and diagnostics for n8n workflows, including workflow validation, execution trace analysis, failure classification, regression detection, and node suggestions, using a read-only credential boundary by default.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
n8n-mcp-cli
Why?
Most n8n MCP integrations give you full admin access — credentials, destructive operations, auto-fix loops. That works for development. It's risky for CI, shared environments, or autonomous agents.
n8n-mcp-cli takes a different approach:
Feature | This MCP | Full admin MCPs |
Workflow validation & health scoring | ✅ Yes | ❌ No |
Execution trace analysis (timing, errors, regression) | ✅ Yes | ❌ No |
Failure classification (logic/infra/data/permission/timeout) | ✅ Yes | ❌ No |
Node suggestions for tasks | ✅ Yes | ❌ No |
n8n version + health check | ✅ Yes | ❌ No |
Credential management | ❌ Excluded | ✅ Yes |
Secret lifecycle | ❌ Excluded | ✅ Yes |
Destructive auto-repair loops | ❌ Excluded | ✅ Some |
Result: A focused operational layer that does validation, diagnostics, and health assessment well, without the risk surface of a full admin wrapper.
Related MCP server: n8n Workflow Builder
Prerequisites
Node.js ≥ 18
n8n running and accessible (tested on 2.12.x, 2.13.x, 2.14.x)
n8n API key with appropriate permissions
Quick Start
1. Install
git clone https://github.com/Souzix76/n8n-mcp-cli.git
cd n8n-mcp-cli
npm install && npm run build2. Configure
cp .env.example .env # Create from template
# Edit .env with your n8n URL and API keyN8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=your_n8n_api_key_here
DEFAULT_TIMEOUT_MS=300003. Run
As MCP server (for Hermes Agent, Claude/Codex, or any MCP client):
# Read-only mode (default)
node dist/mcp/server.js
# Or programmatically with credential mode:
# const server = createMcpServer(client, 'read-only'); // or 'external'As CLI — CLI layer is module-only (no executable entry point yet). Import functions directly:
import { validateV2Project } from './dist/cli/validate.js';
import { generateV2Report, generateV2ReportCi } from './dist/cli/report.js';
// etc.CLI executable coming in Phase 3.
MCP Client Configuration
Hermes Agent / Claude Code (~/.claude.json)
{
"mcpServers": {
"n8n-mcp-cli": {
"type": "stdio",
"command": "node",
"args": ["/path/to/n8n-mcp-cli/dist/mcp/server.js"],
"env": {
"N8N_BASE_URL": "http://localhost:5678",
"N8N_API_KEY": "your_api_key"
}
}
}
}Codex / Any MCP client
The server uses stdio transport — compatible with any MCP client that supports stdio.
How It Works
Credential Boundary (Read-Only by Default)
The MCP server enforces a strict credential boundary via the createMcpServer factory:
Mode | Allowed Tools | Use Case |
read-only (default) |
| Safe inspection, validation, diagnostics |
external | All read-only + | Write operations requiring credentials |
// Programmatic usage:
import { createMcpServer } from './dist/mcp/server.js';
import { N8nClient } from './dist/core/n8n-client.js';
const client = new N8nClient({ baseUrl: 'http://localhost:5678', apiKey: process.env.N8N_API_KEY });
// Read-only (default)
const server = createMcpServer(client, 'read-only');
// External mode (write operations)
const server = createMcpServer(client, 'external');Error handling: CredentialBoundaryError provides actionable remediation messages when a tool is called in an incompatible mode.
Diagnostic Pipeline
The diagnose_workflow tool runs a three-stage diagnostic pipeline:
Execution Data → Trace Analysis → Failure Classification → Regression DetectionTrace Analysis — Per-node timing, errors, item counts, and data flow Failure Classification — Taxonomy: logic | infrastructure | data | permission | timeout Regression Detection — Recurrence patterns across historical runs
Example Output
{
"workflowId": "1hO3EGpPD5es3pi7",
"trace": {
"nodes": 20,
"totalDurationMs": 3450,
"nodeTimings": [
{"name": "HTTP Request", "durationMs": 1200, "status": "success"},
{"name": "IF", "durationMs": 45, "status": "success"}
],
"errors": []
},
"classification": {
"failures": [
{"node": "HTTP Request", "type": "infrastructure", "severity": "warning", "message": "Timeout risk detected"}
]
},
"regression": {
"recurringFailures": 2,
"patterns": ["timeout:webhook", "permission:credential"]
},
"health": {
"score": 92,
"status": "stable"
}
}Tools Reference
Diagnostics & Validation (5 tools)
Tool | Description | Modes |
| Validate a workflow and return risk/health summary without mutating anything | read-only, external |
| Return a workflow health score and risk summary | read-only, external |
| Get n8n server version + health check (notes API limitation) | read-only, external |
| Suggest compatible nodes based on a task description | read-only, external |
| Comprehensive diagnostics: trace analysis, failure classification, regression detection | read-only, external |
Write Operations (1 tool)
Tool | Description | Modes |
| Create a new workflow (placeholder, requires external mode) | external |
CLI (Module-Only)
CLI executable not yet available — CLI layer is module-only. Use MCP server or import functions directly.
// Available modules in dist/cli/
import { validateV2Project } from './dist/cli/validate.js';
import { runV2Suite } from './dist/cli/run.js';
import { generateV2Report, generateV2ReportCi } from './dist/cli/report.js';
import { registryGenerate, registryValidate } from './dist/cli/registry.js';
import { startMcpServer } from './dist/cli/mcp.js';Executable n8n-mcp-cli command coming in Phase 3.
Troubleshooting
Issue | Cause | Fix |
| n8n not running or wrong | Verify n8n is up on port 5678; check |
| Invalid or missing | Generate key in n8n UI → Settings → API; update |
| API key lacks required permissions | Ensure key has workflow read/write access |
|
| Increase timeout in |
Architecture
├── cli/ # CLI layer — CI/CD, scriptable checks, reports
├── core/ # Shared core — safety, validation, health, retry, errors
├── diagnostics/ # Trace analysis, failure classification, regression
├── mcp/ # MCP layer — AI-safe tool surface, credential boundary
├── recommendations/ # Health scoring, compatibility checks
├── reports/ # JSON, Markdown, HTML, JUnit reports
├── registry/ # MCP registry manifest
├── testing/ # Assertion and suite execution foundations
└── examples/ # CI validation, health check examplesDesign Principles
Read-only by default — Safe inspection without mutation
Dry-run for mutation paths — Validate before write
Explicit credential boundary —
read-onlyvsexternalmodesStructured diagnostics over raw logs — Evidence-based traces
Environment-aware validation — Context matters
Production safety over feature volume — Trusted operational layer
No credential lifecycle management — Won't read, create, or delete credentials
No destructive auto-repair loops — Reports issues, doesn't auto-fix
Example Configs
The examples/ directory includes ready-to-use workflows:
File | Description |
| CI validation workflow example |
| Health check workflow example (read-only mode) |
Safety Posture
Included
Workflow validation and health scoring
Execution trace analysis (timing, errors, data flow)
Failure classification with taxonomy
Regression detection across historical runs
Node suggestions for tasks
n8n version + health check
MCP registry manifest generation/validation
Multi-format reporting (JSON, Markdown, HTML, JUnit)
Deliberately Excluded
Credentials management
Secrets lifecycle
Destructive restore flows
Autonomous LLM auto-fix loops
Production deployment operations
Roadmap
Phase 1 — Governance and safety foundation (Credential Boundary, CLI flags, MCP tools)
Phase 2 — n8n API integration (real
/api/v1/endpoints, SQLite API key extraction)Phase 3 — Validation and suite execution
Phase 4 — Diagnostics and regression analysis
Phase 5 — Recommendation and compatibility engine
Phase 6 — Reporting and operational maturity
Contributing
Fork the repo
Create a feature branch (
git checkout -b feat/my-feature)Commit changes (
git commit -m 'feat: add my feature')Push to branch (
git push origin feat/my-feature)Open a Pull Request
License
Built for n8n operators who want validation and diagnostics without the risk surface.
Compatible with Hermes Agent, Claude/Codex, and any MCP client.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Static n8n workflow validator: workflow errors and repair suggestions. No execution.
Diagnose AI workflows for failure, security, and handoff risks — RED/AMBER/GREEN per node.
Security scanner for n8n workflows + live MCP Trust-Check. 18 rules, OWASP mapped. Paid x402 API.
Build, check and fix n8n workflows from Claude, Cursor or ChatGPT. Built on 1,100+ real n8n node definitions and curated templates, with a validator that repairs common mistakes (wrong node types, missing settings) and returns JSON ready to import into n8n. Sign in with a free gydmation.com account; nothing to install.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables orchestration and management of n8n workflows through tools for creating, updating, diagnosing failed executions, auto-fixing workflows, and installing community nodes.-
- AlicenseNot gradedqualityBmaintenanceEnables AI-powered building, optimization, debugging, and management of n8n workflows directly from Claude. Features workflow analysis, execution monitoring, security audits, drift detection, and intelligent error debugging with best practices guidance.1MIT
- AlicenseBqualityCmaintenanceSafe MCP server and CLI tool for testing, scoring, and inspecting n8n workflows. Features 19 tools for workflow testing, execution traces, tiered scoring, and a built-in node catalog with 800+ node types. Designed with safety-first approach: no credential management, no secrets lifecycle, no auto-fix loops.191MIT
- AlicenseAqualityCmaintenanceLints n8n workflow exports and returns machine-readable findings with per-rule fixes, helping agents and reviewers catch reliability gaps such as missing error workflows, retries that swallow errors, unauthenticated webhooks, and hardcoded secrets without sending data anywhere.3MIT