Content
# n8n MCP Server
MCP server for [n8n](https://n8n.io) workflow automation. Built for AI agents (Claude Code, Claude Desktop, Cursor) that manage n8n workflows programmatically.
Smart validation, auto-fix for common pitfalls, embedded knowhow database, execution polling, credential management, and node discovery — in one server.
## Why this exists
n8n's AI workflow features are enterprise-only. I wanted AI agents to build and manage my workflows, so I built this MCP server. It gives Claude (or any MCP-compatible agent) full programmatic control over n8n — and auto-fixes 7 common API quirks that trip up agents along the way.
## Quick Start
```bash
git clone https://github.com/r-ms/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
```
## Configuration
All configuration is via environment variables passed through your MCP client config.
| Variable | Required | Description |
|----------|----------|-------------|
| `N8N_API_URL` | Yes | n8n instance URL (e.g. `http://localhost:5678`) |
| `N8N_API_KEY` | Yes | n8n Public API key (Settings → API → Create API Key) |
| `N8N_WEBHOOK_URL` | No | Separate base URL for webhooks if behind a reverse proxy. Defaults to `N8N_API_URL` |
| `N8N_MCP_API_KEY` | No | n8n MCP Server API key for node discovery tools (Settings → MCP Server). Requires n8n 2.14+ |
### Claude Code
Add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"n8n": {
"type": "stdio",
"command": "node",
"args": ["/path/to/n8n-mcp/dist/index.js"],
"env": {
"N8N_API_URL": "http://localhost:5678",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"n8n": {
"command": "node",
"args": ["/path/to/n8n-mcp/dist/index.js"],
"env": {
"N8N_API_URL": "http://localhost:5678",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
## Tools (20)
### Workflow Management (8)
| Tool | Description |
|------|-------------|
| `n8n_list_workflows` | List all workflows, filter by active status or name |
| `n8n_get_workflow` | Get full workflow definition with pre-flight validation warnings |
| `n8n_create_workflow` | Create workflow with auto-fix for common pitfalls |
| `n8n_update_workflow` | Partial update — auto-hydrates missing fields from current version |
| `n8n_update_workflow_json` | Deploy a complete workflow from a JSON string. Optionally activate |
| `n8n_delete_workflow` | Delete workflow (auto-deactivates first, requires confirmation) |
| `n8n_activate_workflow` | Activate workflow (enable triggers) |
| `n8n_deactivate_workflow` | Deactivate workflow (stop triggers) |
### Execution & Monitoring (4)
| Tool | Description |
|------|-------------|
| `n8n_list_executions` | List recent executions with status filtering and success rate |
| `n8n_get_execution` | Detailed execution trace — node timing, items, errors, knowhow hints. `verbose` mode for full output |
| `n8n_run_workflow` | Trigger via webhook. Waits for result by default (120s timeout), returns full trace |
| `n8n_diagnose_workflow` | Run all pre-flight checks on a workflow without executing |
### Ad-hoc Execution (1)
| Tool | Description |
|------|-------------|
| `n8n_run_adhoc` | Run a one-off node chain — creates temp workflow, executes via webhook, returns trace, auto-cleans up |
### Credentials (3)
| Tool | Description |
|------|-------------|
| `n8n_list_credentials` | List all credentials (ID, name, type) |
| `n8n_get_credential_schema` | Get JSON schema for a credential type — shows required fields before creating |
| `n8n_create_credential` | Create a credential. On error, auto-fetches schema as a hint |
### Node Discovery (3) — requires `N8N_MCP_API_KEY`
| Tool | Description |
|------|-------------|
| `n8n_search_nodes` | Search available node types by keyword. Returns IDs and discriminators |
| `n8n_get_node_params` | Get TypeScript type definitions for node parameters. Prevents guessing |
| `n8n_get_suggested_nodes` | Curated node recommendations by category (chatbot, scheduling, scraping, etc.) |
### Diagnostics (1)
| Tool | Description |
|------|-------------|
| `n8n_search_knowhow` | Search the embedded knowhow database for solutions to n8n issues |
## Pre-flight Validation
Applied automatically on every `create` and `update`. Catches and fixes common n8n pitfalls before they reach the API:
| Issue | Auto-fix |
|-------|----------|
| Code node v2 without `language` param | Downgrade to v1 |
| Spaces in trigger node names (break webhooks) | Remove spaces, rewrite connections |
| Missing `settings` field | Add `{executionOrder: "v1"}` |
| `ExecuteWorkflow` workflowId as plain string | Wrap in `{value: "ID"}` |
| MongoDB `find` without `alwaysOutputData` | Set to `true` |
| SplitInBatches v3 wired to wrong output | Move connections from output 0 (done) to output 1 (loop) |
| Missing `webhookId` on trigger nodes | Auto-generate |
## Knowhow Database
11 pattern-matched entries. When an error occurs, the server matches it against known n8n issues and surfaces the solution:
| Pattern | Solution |
|---------|----------|
| `require()` blocked in sandbox | Use n8n native nodes instead of Code node imports |
| ECONNREFUSED in Code node | Task Runner is network-isolated — use HTTP Request node |
| MongoDB limit type error | Must be integer, not expression string |
| Sub-workflow not published | Activate sub-workflows before parent |
| Webhook 404 | Check: active? spaces in name? webhookId set? |
## Resilience
- **Retry with exponential backoff** — 3 retries on network errors and 502/503
- **Execution polling** — `n8n_run_workflow` polls every 2s until completion or timeout
- **Webhook 404 recovery** — fuzzy-matches against active webhook paths and suggests corrections
## Requirements
- Node.js 18+
- n8n with Public API enabled (any version)
- n8n 2.14+ for node discovery tools (optional)
## License
MIT
