helbertparanhos/n8n-pro-mcp

> Full-instance management for self-hosted n8n — including queue mode — through the Model Context Protocol. 51 tools covering workflows, executions, tags, credentials, variables, projects, users, security audit, source control and health monitoring.
n8n-pro-mcp connects Claude Code, Claude Desktop, Cursor or any MCP client to your n8n instance via the official n8n public API v1, with automatic cursor pagination, exponential-backoff retry on reads (writes and webhook calls are never retried, so side effects can't duplicate), and offline workflow validation that catches the classic n8n mistakes (malformed {{ }} expressions, webhook data accessed without .body, Code nodes missing return [{json: {...}}]) **before** they reach your instance.
Why this one?
- **Queue mode first-class** — list_running_executions (live queue view), get_execution_stats (success rate + average duration per workflow) and check_health (healthz, readiness, API auth) were built for instances running EXECUTIONS_MODE=queue with workers and webhook processors. N8N_WEBHOOK_BASE_URL lets webhook calls target dedicated webhook processors.
- **Complete API v1 coverage** — tags, variables, projects, users, source control and cross-project transfers, beyond the usual workflow/execution CRUD.
- **Offline validation built in** — validate_workflow_json checks structure, connection integrity, orphan nodes, expression syntax, webhook .body access, Code node return format and hardcoded secrets without any API call. create_workflow/update_workflow run it automatically and refuse invalid payloads.
- **Safe partial updates** — update_workflow fetches the current workflow, merges only what you pass and strips read-only fields, so you never lose nodes by sending an incomplete PUT.
- **Tags by name** — set_workflow_tags accepts tag names and creates missing ones; no manual ID juggling.
- **Ops compositions the raw API doesn't have** — summarize_execution_error (just the failing node + error, not a giant JSON dump), prune_executions (bulk cleanup with dry run), wait_for_execution (poll until terminal), clone_workflow and set_workflows_active_by_tag (tag-based kill switch).
Installation
From source:
When running from source, you can copy .env.example to .env **in the project root** — the server loads it from the package root, not the working directory. When installed via npx, set the variables through your MCP client config instead (the .env file is not read from the npx cache).
Configuration
| Variable | Required | Description |
|----------|----------|-------------|
| N8N_API_URL | ✅ | Base URL of your instance (e.g. https://n8n.yourdomain.com) — no /api/v1 suffix |
| N8N_API_KEY | ✅ | API key from n8n → **Settings → n8n API → Create API key** |
| N8N_WEBHOOK_BASE_URL | — | Separate base URL for webhook calls (queue mode with dedicated webhook processors) |
| N8N_API_TIMEOUT_MS | — | Per-request timeout in ms (default 30000) |
| N8N_MAX_RETRIES | — | Retries on 429/5xx/network errors — applied to GET requests only, never to writes or webhook calls (default 3, 0 disables) |
Claude Code
Or in .claude/settings.json / .mcp.json:
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Cursor
Same JSON block in Cursor's MCP settings (.cursor/mcp.json).