n8n-pro-mcp

# 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. [](https://www.npmjs.com/package/n8n-pro-mcp) [](https://opensource.org/licenses/MIT) [](https://github.com/helbertparanhos/n8n-pro-mcp/stargazers) [](https://github.com/helbertparanhos/n8n-pro-mcp/network/members) [](https://github.com/helbertparanhos/n8n-pro-mcp/issues) [](https://glama.ai/mcp/servers/helbertparanhos/n8n-pro-mcp) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) [](https://claude.ai/code) [](https://cursor.sh) [](https://claude.ai/download) [](https://www.instagram.com/helbertparanhos) [](https://www.youtube.com/@stratacademy) [](https://www.linkedin.com/in/helbert-paranhos/) [](https://buymeacoffee.com/helbertparanhos) [](https://stratacademy.com.br) `n8n-pro-mcp` connects Claude Code, Claude Desktop, Cursor or any MCP client to your n8n instance via the official [n8n public API v1](https://docs.n8n.io/api/), 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 ```bash npm install -g n8n-pro-mcp # or use npx, no install needed ``` From source: ```bash git clone https://github.com/helbertparanhos/n8n-pro-mcp.git && cd n8n-pro-mcp npm install npm run build ``` 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 ```bash claude mcp add n8n-pro --env N8N_API_URL=https://n8n.yourdomain.com --env N8N_API_KEY=your-key -- npx -y n8n-pro-mcp ``` Or in `.claude/settings.json` / `.mcp.json`: ```json { "mcpServers": { "n8n-pro": { "command": "npx", "args": ["-y", "n8n-pro-mcp"], "env": { "N8N_API_URL": "https://n8n.yourdomain.com", "N8N_API_KEY": "your-api-key" } } } } ``` ### Claude Desktop `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows): ```json { "mcpServers": { "n8n-pro": { "command": "npx", "args": ["-y", "n8n-pro-mcp"], "env": { "N8N_API_URL": "https://n8n.yourdomain.com", "N8N_API_KEY": "your-api-key" } } } } ``` ### Cursor Same JSON block in Cursor's MCP settings (`.cursor/mcp.json`). ## Tools (51) ### Workflows (12) | Tool | Description | |------|-------------| | `list_workflows` | List with filters (active, tags, project, name) + auto pagination | | `get_workflow` | Full JSON or lightweight summary of one workflow | | `create_workflow` | Create from JSON, with automatic offline validation | | `update_workflow` | Partial update — fetch, merge, validate, PUT | | `delete_workflow` | Permanently delete | | `activate_workflow` / `deactivate_workflow` | Toggle triggers | | `transfer_workflow` | Move between projects | | `search_workflows` | Free-text search across names, node names and node types | | `clone_workflow` | Duplicate a workflow as an inactive copy | | `set_workflows_active_by_tag` | Bulk activate/deactivate by tag, with dry run | | `validate_workflow_json` | Offline validation, no API call | ### Executions (10) | Tool | Description | |------|-------------| | `list_executions` | Filter by status/workflow/project, with durations | | `get_execution` | Summary or full node-level run data for debugging | | `delete_execution` | Remove an execution record | | `retry_execution` | Retry a failed/stopped execution | | `list_running_executions` | **Queue-mode live view** of running/queued executions | | `run_webhook` | Trigger workflows via production or test webhook | | `wait_for_execution` | Poll an execution until it reaches a terminal state | | `summarize_execution_error` | Failing node + error message only — no giant JSON dump | | `prune_executions` | Bulk-delete old execution records, dry run by default | | `get_execution_stats` | Success rate + avg duration per workflow over a sample | ### Tags (6) `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `get_workflow_tags`, `set_workflow_tags` (by name, auto-creates missing tags). ### Credentials (4) `create_credential`, `delete_credential`, `get_credential_schema`, `transfer_credential`. Secrets are write-only — the n8n API never returns credential data. ### Variables (4) `list_variables`, `create_variable`, `update_variable`, `delete_variable` (licensed feature). ### Projects (7) `list_projects`, `create_project`, `update_project`, `delete_project`, plus member management: `add_user_to_project`, `remove_user_from_project`, `change_user_project_role` (licensed feature). ### Users (5) `list_users`, `get_user`, `create_user` (invite), `delete_user`, `change_user_role`. ### System (3) | Tool | Description | |------|-------------| | `check_health` | healthz + readiness (DB) + API auth, with a plain-language summary | | `generate_audit` | n8n's built-in security audit (credentials, database, nodes, filesystem, instance) | | `pull_source_control` | Pull from the connected git repository | ## Queue mode playbook With `EXECUTIONS_MODE=queue` (main + workers + Redis): 1. `check_health` — confirms the main process and DB are up. 2. `list_running_executions` — what is actually in flight right now; a growing list with old `startedAt` values means workers are starved or stuck. 3. `get_execution_stats` — which workflows fail or crawl; sorted worst-first by success rate. 4. `run_webhook` with `N8N_WEBHOOK_BASE_URL` pointing at your webhook processors to test the production ingestion path end to end. ## Development ```bash npm test # build + unit tests (validation rules, client helpers, .env parser) npm run watch # incremental compile npm run inspector # interactive testing with @modelcontextprotocol/inspector ``` CI (GitHub Actions) runs build, tests and `npm audit` on every push and PR. ## Requirements - Node.js ≥ 18 - n8n instance with the public API enabled (`N8N_PUBLIC_API_DISABLED` not set) and an API key - Variables, projects and source-control tools require the corresponding licensed n8n features ## 👤 Author Created by **[Helbert Paranhos](https://github.com/helbertparanhos)** at **[Strat Academy](https://stratacademy.com.br)**. [](https://www.instagram.com/helbertparanhos) [](https://www.youtube.com/@stratacademy) [](https://www.linkedin.com/in/helbert-paranhos/) [](https://buymeacoffee.com/helbertparanhos) If this project helped you, consider starring ⭐ the repository and following **[Strat Academy](https://stratacademy.com.br)** for more AI automation tooling. ## 📄 License MIT © [Helbert Paranhos](https://github.com/helbertparanhos) / [Strat Academy](https://stratacademy.com.br) — see [LICENSE](LICENSE).