mcp-n8n

# MCP n8n Server

[![npm version](https://img.shields.io/npm/v/mcp-n8n.svg)](https://www.npmjs.com/package/mcp-n8n)
[![npm downloads](https://img.shields.io/npm/dm/mcp-n8n.svg)](https://www.npmjs.com/package/mcp-n8n)
[![CI](https://github.com/leonardosepulvedat/mcp-n8n/actions/workflows/ci.yml/badge.svg)](https://github.com/leonardosepulvedat/mcp-n8n/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![n8n](https://img.shields.io/badge/n8n-compatible-orange.svg)](https://n8n.io)

**Operate and build n8n from Cursor or Claude** — administration of your instance (users, projects, executions, audit) **and** a full builder loop: a catalog of **560 nodes with real parameter schemas** extracted from the official n8n packages, validation before saving, automatic repair, snapshots with rollback and diff, per-node execution debugging, health reports, and full-instance backup.

Two env vars. Runs on your machine (stdio) or as a remote HTTP server. No hosted account.

---

## 🎯 Token Optimization

**This server is optimized to minimize token consumption**, addressing one of the biggest issues with MCP servers - excessive API token usage.

### What We've Optimized:
- **90% reduction** in tokens for workflow listing with new `n8n_list_workflows_summary` endpoint
- **Field filtering** - request only the data you need
- **Smart defaults** - reduced from 100 to 10-20 results per query
- **Intelligent warnings** - alerts when operations will consume significant tokens

**See [TOKEN_OPTIMIZATION.md](./TOKEN_OPTIMIZATION.md) for detailed usage guide.**

---

## ✨ Features

### 🔄 Workflow Management
- **Create & Deploy**: Build workflows with natural language descriptions
- **CRUD Operations**: Full lifecycle management (Create, Read, Update, Delete)
- **Activation Control**: Enable/disable workflows on demand
- **Project Transfer**: Move workflows between projects seamlessly
- **Tag Management**: Organize workflows with custom tags

### 📊 Execution Monitoring
- **Real-time Tracking**: Monitor workflow executions with advanced filters
- **Detailed Insights**: Access full execution data and logs
- **Error Recovery**: Retry failed executions automatically
- **Cleanup Tools**: Manage execution history efficiently

### 🔐 Credential Management
- **Secure Creation**: Add credentials for any service
- **Schema Discovery**: Auto-discover required fields for credential types
- **Project Isolation**: Transfer credentials between projects safely
- **Type Support**: Compatible with all n8n credential types

### 🧱 Workflow Builder
- **Full node catalog — 560 nodes with real schemas**: extracted directly from `n8n-nodes-base` and `@n8n/n8n-nodes-langchain` (parameters with types, allowed options, display conditions, credentials, latest typeVersion), regenerated weekly by CI. Search with `n8n_search_nodes`, inspect with `n8n_get_node`
- **Real validation**: `n8n_validate_workflow` checks against the real schemas — nonexistent node types, missing required params (including conditionally required ones), invalid option values, wrong typeVersion, broken connections — *before* save/activate
- **Expression linting**: detects `{{ }}` expressions missing the `=` prefix and references to nodes that don't exist in the workflow
- **Automatic repair**: `n8n_autofix_workflow` fixes missing typeVersion/positions, duplicate names, dangling connections and expression prefixes — preview first, apply with a snapshot
- **Surgical edits**: `n8n_update_workflow_partial` adds/removes nodes and connections without rewriting the whole flow
- **Public templates**: search and import from n8n.io (`n8n_search_public_templates`, `n8n_import_public_template`) plus 100 bundled templates as a fallback
- **Guided prompts**: MCP prompts `build-workflow` and `fix-workflow` walk any agent through the full build/validate/test/repair loop

### 🔬 Deep Debugging & Health
- **Per-node execution data**: `n8n_get_node_execution_data` shows exactly what data flowed through one node (status, item counts, output samples, error details) without downloading the whole execution
- **Debug loop**: `n8n_debug_last_error` returns the failing node and message from the last error
- **Health reports**: `n8n_workflow_health` computes success rate, failure count, average duration and last failure per workflow from recent executions, sorted worst-first

### 🛡️ Safety Net & Real Testing
- **Automatic snapshots**: before every update, partial edit, autofix, or delete, the previous state is saved locally (`~/.mcp-n8n/snapshots`, configurable with `N8N_SNAPSHOT_DIR`)
- **Rollback**: `n8n_rollback_workflow` restores any snapshot — even recreates a deleted workflow (`recreate=true`)
- **Diff**: `n8n_diff_workflow_snapshot` compares a snapshot against the current state (nodes added/removed/modified, changed parameters, connection changes) before deciding to roll back
- **Full-instance backup**: `n8n_export_all_workflows` saves every workflow as JSON files; `n8n_import_workflows` restores them
- **End-to-end testing**: `n8n_trigger_webhook` calls a Webhook-trigger workflow on the instance and returns the real HTTP response, so the agent can verify the flow actually works

### 🎯 Bundled Templates
- 100 local starting points with keyword matching, if you prefer not to hit n8n.io

### 🏗️ Organization & Administration
- **Tags**: Categorize and organize resources
- **Variables**: Centralized environment variable management
- **Projects**: Multi-tenant project support
- **Users & Permissions**: Complete access control management
- **Audit Logs**: Generate security and compliance reports

---

## 🚀 Quick Start

### Installation via npm (Recommended)

This is the easiest way to get started:

```bash
npm install -g mcp-n8n
```

### Configuration

1. **Get your n8n API credentials**:
   - Navigate to your n8n instance → Settings → n8n API
   - Generate a new API key

2. **Configure Claude Desktop**:

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

**Option A - Using global installation (if you ran `npm install -g mcp-n8n`):**
```json
{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}
```

`N8N_TOOLSETS` is optional (`all` by default). Use `core,builder` if you want operations + creation without user/project admin tools. Use `admin` only for instance administration.

### Remote HTTP mode (optional)

By default the server communicates over stdio (local). To run it as a shared remote server (e.g. in Docker or on a VPS), set a port:

```bash
N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n
```

This exposes the MCP protocol over streamable HTTP on port 3000 plus a `GET /health` endpoint. `N8N_MCP_HTTP_TOKEN` is strongly recommended: when set, every request must include `Authorization: Bearer <token>`. Point any MCP client that supports streamable HTTP at `http://your-host:3000` with that header.

**Option B - Using npx (no installation needed, always latest version):**
```json
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

3. **Configure Cursor**:

Add to Cursor MCP settings (Settings → Extensions → MCP):

**Recommended - Using npx (always uses latest version):**
```json
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

> **Note**: Cursor requires using `npx` for MCP servers. The `-y` flag automatically installs/updates the package without prompting.

**Option C - Docker:**

```bash
docker build -t mcp-n8n .
```

```json
{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

The `/data` volume persists workflow snapshots between runs.

4. **Restart Claude Desktop or Cursor**

---

## 💬 Usage Examples

Once configured, interact with n8n using natural language:

### Creating Workflows

```plaintext
"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"
```

```plaintext
"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"
```

### Using Templates

```plaintext
"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template
```

```plaintext
"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template
```

### Managing Workflows

```plaintext
"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage
```

```plaintext
"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed
```

```plaintext
"Deactivate the 'Daily Backup' workflow"
```

```plaintext
"What went wrong with execution abc123?"
```

### Monitoring & Debugging

```plaintext
"Show me the last 10 failed executions"
```

```plaintext
"Retry all failed executions from workflow xyz456"
```

```plaintext
"Delete all successful executions older tha