n8n-pro-mcp
README.md
# 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).
TDQS
A3.7/5.0
Scored across 51 tools
Disambiguation5/5
Each tool has a clearly distinct purpose, with detailed descriptions that prevent ambiguity. Even with 51 tools, operations are well-separated across different resources (workflows, credentials, users, projects, etc.) and actions.
Naming Consistency5/5
All tool names use lowercase snake_case with a verb_noun pattern (e.g., activate_workflow, list_users). The naming is highly consistent with no mixing of conventions.
Tool Count4/5
The 51 tools cover a broad domain (n8n instance management), and each tool appears justified. However, the count is high; a slightly more consolidated set could be conceivable, but the current scope earns a 4.
Completeness5/5
The tool set covers the full lifecycle of workflows, credentials, users, projects, tags, variables, and executions, including advanced operations like cloning, validation, bulk actions, and health monitoring. No obvious gaps are present.
Maintenance
ActivityMaintained
ResponsivenessNo issues