npm package: @neterius/n8n-mcp
Description: The most complete MCP server for n8n — 54 tools, 7 embedded skills, i18n, offline node catalog, diagnostics, auto-fix, analytics and more
Author: Neterius
Latest version: 1.6.0

<p align="center">
  <img src="https://img.shields.io/npm/v/@neterius/n8n-mcp?style=flat-square&color=blue" alt="npm version" />
  <img src="https://img.shields.io/npm/l/@neterius/n8n-mcp?style=flat-square" alt="license" />
  <img src="https://img.shields.io/badge/tools-45-green?style=flat-square" alt="45 tools" />
  <img src="https://img.shields.io/badge/skills-7-orange?style=flat-square" alt="7 skills" />
  <img src="https://img.shields.io/badge/i18n-es%20%7C%20en-purple?style=flat-square" alt="i18n" />
</p>

# @neterius/n8n-mcp

> The most complete MCP server for n8n — 45 tools + 7 embedded skills to manage, diagnose, and auto-fix your workflows from any AI assistant.

Connect **Claude**, **GitHub Copilot**, **Cursor**, or any MCP-compatible client directly to your n8n instance. Manage workflows, analyze executions, discover nodes, validate configurations, auto-fix failing workflows, and access an embedded knowledge base — all through natural language.

---

## Features

| Category | Tools | Highlights |
|----------|-------|------------|
| **Workflows** | 7 | Full CRUD + activate/deactivate |
| **Executions** | 3 | List (with date filters), inspect, delete |
| **Diagnostics** | 4 | Failed executions, deep diagnosis, patch nodes, add nodes |
| **Auto-fix** | 1 | Skill-aware confidence-based repair with catalog cross-reference |
| **Node Discovery** | 3 | Offline catalog of 2650+ nodes with search + live sync |
| **Validation** | 2 | Validate individual nodes or entire workflows |
| **Partial Update** | 1 | 17 granular operations (add/remove/rewire nodes, connections, settings…) |
| **Testing** | 2 | Execute workflows, test webhooks |
| **Versioning** | 2 | List versions, rollback |
| **Templates** | 2 | Search n8n.io templates, deploy to your instance |
| **Analytics** | 2 | Success/fail rates, duration stats, hourly distribution, timeline |
| **Variables** | 2 | List and upsert environment variables |
| **Credentials** | 4 | List, get schema, create, delete |
| **Tags** | 3 | List, create, delete |
| **Users** | 2 | List users, get user details |
| **Static Data** | 2 | Get and reset workflow static data (caches) |
| **Skills** | 2 | Embedded n8n knowledge base (7 skills, 36 docs) |
| **Health** | 1 | Instance health check |

**Total: 45 tools** across 18 modules.

---

## Quick Start

### 1. Install

```bash
npm install -g @neterius/n8n-mcp
# or
pnpm add -g @neterius/n8n-mcp
```

### 2. Get your n8n API Key

In your n8n instance: **Settings → API → Create API Key**

### 3. Configure your MCP client

#### Claude Desktop / Claude Code

Add to your MCP config (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@neterius/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "MCP_LANG": "es"
      }
    }
  }
}
```

#### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@neterius/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "MCP_LANG": "es"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@neterius/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "MCP_LANG": "en"
      }
    }
  }
}
```

### 4. Start using it

Just ask your AI assistant:

- *"List my n8n workflows"*
- *"Why is my PR Review Agent failing?"*
- *"Auto-fix the failing workflows"*
- *"Show me execution stats for the last week"*
- *"Search for a Slack node and add it to my workflow"*

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `N8N_API_URL` | Yes | — | Base URL of your n8n instance |
| `N8N_API_KEY` | Yes | — | API key for authentication |
| `MCP_LANG` | No | `es` | Language for tool descriptions (`es` \| `en`) |

---

## All 45 Tools

### Health
| Tool | Description |
|------|-------------|
| `n8n_health_check` | Check n8n instance connectivity and version |

### Workflows
| Tool | Description |
|------|-------------|
| `n8n_list_workflows` | List all workflows |
| `n8n_get_workflow` | Get full workflow definition by ID |
| `n8n_create_workflow` | Create a new workflow from JSON |
| `n8n_update_workflow` | Replace entire workflow definition |
| `n8n_delete_workflow` | Delete a workflow |
| `n8n_activate_workflow` | Activate a workflow |
| `n8n_deactivate_workflow` | Deactivate a workflow |

### Executions
| Tool | Description |
|------|-------------|
| `n8n_list_executions` | List executions with optional filters (status, workflow, date range) |
| `n8n_get_execution` | Get execution details including data |
| `n8n_delete_execution` | Delete an execution |

### Diagnostics
| Tool | Description |
|------|-------------|
| `n8n_get_failed_executions` | Get recent failed executions with error details |
| `n8n_diagnose_workflow` | Deep analysis: errors, patterns, recommendations |
| `n8n_patch_workflow_nodes` | Patch parameters on specific nodes |
| `n8n_add_node_to_workflow` | Add a new node to an existing workflow |

### Auto-fix
| Tool | Description |
|------|-------------|
| `n8n_autofix_workflow` | Analyze failures and apply skill-aware confidence-based fixes |

### Node Discovery
| Tool | Description |
|------|-------------|
| `n8n_search_nodes` | Search the offline catalog of 2650+ nodes |
| `n8n_get_node_info` | Get detailed info about a specific node type |
| `n8n_sync_node_catalog` | Scan instance workflows and compare against offline catalog |

### Validation
| Tool | Description |
|------|-------------|
| `n8n_validate_node` | Validate node configuration against catalog |
| `n8n_validate_workflow` | Check workflow for orphan connections, missing triggers, etc. |

### Partial Update
| Tool | Description |
|------|-------------|
| `n8n_update_partial_workflow` | 17 granular operations: addNode, removeNode, updateNode, moveNode, enableNode, disableNode, addConnection, removeConnection, rewireConnection, updateSettings, updateName, addTag, removeTag, activateWorkflow, deactivateWorkflow, replaceConnections, cleanStaleConnections |

### Testing
| Tool | Description |
|------|-------------|
| `n8n_test_workflow` | Execute a workflow and return results |
| `n8n_run_webhook_test` | Send a test HTTP request to a webhook |

### Versioning
| Tool | Description |
|------|-------------|
| `n8n_list_workflow_versions` | List version history of a workflow |
| `n8n_rollback_workflow` | Rollback to a previous version |

### Templates
| Tool | Description |
|------|-------------|
| `n8n_search_templates` | Search the n8n.io template library |
| `n8n_deploy_template` | Deploy a template to your instance |

### Analytics
| Tool | Description |
|------|-------------|
| `n8n_workflow_stats` | Success/fail rates, avg duration, hourly distribution |
| `n8n_execution_timeline` | Execution timeline with failure details |

### Variables
| Tool | Description |
|------|-------------|
| `n8n_list_variables` | List all environment variables |
| `n8n_set_variable` | Create or update a variable (upsert) |

### Credentials
| Tool | Description |
|------|-------------|
| `n8n_list_credentials` | List available credentials |
| `n8n_get_credential_schema` | Get the JSON schema for a credential type |
| `n8n_create_credential` | Create a new credential |
| `n8n_delete_credential` | Delete a credential by ID |

### Tags
| Tool | Description |
|------|-------------|
| `n8n_list_tags` | List all tags |
| `n8n_create_tag` | Create a new tag |
| `n8n_delete_tag` | Delete a tag by ID |

### Users
| Tool | Description |
|------|-------------|
| `n8n_list_users` | List all users in the instance |
| `n8n_get_user` | Get details of a specific user |

### Static Data
| Tool | Description |
|------|-------------|
| `n8n_get_static_data` | Get a workflow's static data (persistent cache) |
| `n8n_reset_static_data` | Reset a workflow's static data to empty |

### Skills (Knowledge Base)
| Tool | Description |
|------|-------------|
| `n8n_list_skills` | List the 7 embedded n8n skills with descriptions |
| `n8n_get_skill` | Get the full content of a skill (expert guides for building workflows) |

> **Skills include**: MCP Tools Expert, Workflow Patterns, Expression Syntax, Validation Expert, Node Configuration, Code JavaScript, Code Python — 36 expert documents embedded offline.

---

## Architecture

```
src/
├── index.ts              # Entry point (dynamic version from package.json)
├── n8n-client.ts         # HTTP client for n8n REST API v1
├── i18n/
│   ├── index.ts          # Language loader (MCP_LANG)
│   ├── es.ts             # Spanish translations (default)
│   └── en.ts             # English translations
├── catalog/
│   └── nodes.ts          # Offline catalog of 2650+ n8n nodes
├── skills/
│   └── data.ts           # 7 embedded n8n skills (36 expert docs)
└── tools/
    ├── types.ts           # Shared types (ToolContext, helpers)
    ├── index.ts           # Tool registry (18 modules)
    ├── health.ts          # 1 tool
    ├── workflows.ts       # 7 tools
    ├── executions.ts      # 3 tools
    ├── credentials.ts     # 4 tools
    ├── tags.ts            # 3 tools
    ├── users.ts           # 2 tools
    ├── diagnostics.ts     # 4 tools
    ├── node-discovery.ts  # 3 tools
    ├── validation.ts      # 2 tools
    ├── partial-update.ts  # 1 tool (17 operations)
    ├── testing.ts         # 2 tools
    ├── versioning.ts      # 2 tools
    ├── templates.ts       # 2 tools
    ├── analytics.ts       # 2 tools
    ├── variables.ts       # 2 tools
    ├── autofix.ts         # 1 tool
    ├── static-data.ts     # 2 tools
    └── skills.ts          # 2 tools
```

---

## i18n

Tool names, descriptions, and error messages are fully translatable. Set `MCP_LANG=es` (default) or `MCP_LANG=en`.

Adding a new language: create `src/i18n/{lang}.ts` mirroring the structure of `es.ts`, then add it to the loader in `src/i18n/index.ts`.

---

## Development

```bash
# Clone
git clone https://github.com/fernandox2/n8n-mcp.git
cd n8n-mcp

# Install
pnpm install

# Configure
cp .env.example .env
# Edit .env with your n8n credentials

# Dev mode (hot reload)
pnpm run dev

# Build
pnpm run build

# Production
pnpm run start
```

---

## Contributing

Contributions are welcome! Please open an issue or pull request.

---

## License

[MIT](LICENSE) © [Neterius](https://neterius.com)

---

<p align="center">
  Built with ❤️ by <a href="https://neterius.com">Neterius</a>
</p>