<div align="center">

<img src="https://img.shields.io/badge/n8n-MCP_Server-FF6D5A?style=for-the-badge&logo=n8n&logoColor=white" alt="n8n MCP Server"/>

# 🤖 n8n MCP Server — AI-Powered Automation

### *The Most Advanced Model Context Protocol Server for n8n — 54 Tools, Full Control*

[![Version](https://img.shields.io/badge/version-2.0.0-brightgreen?style=for-the-badge&logo=github)](https://github.com/SohailShabbir867/n8n_mcp/releases)
[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.x-6f42c1?style=for-the-badge&logo=typescript&logoColor=white)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)
[![n8n API](https://img.shields.io/badge/n8n_API-v1-FF6D5A?style=for-the-badge&logo=n8n&logoColor=white)](https://docs.n8n.io/api/)

<br/>

> **Give Claude, Cursor, or any MCP-compatible AI full control over your n8n instance.**  
> Build workflows, debug executions, manage credentials, audit security — all by chatting with AI.

<br/>

[🚀 Quick Start](#-quick-start) • [🛠️ 54 Tools](#️-tool-reference-54-tools) • [💻 Client Setup](#-client-setup-claude--cursor--windsurf) • [🐳 Docker](#-docker) • [💡 AI Prompts](#-example-ai-prompts) • [🔍 FAQ](#-troubleshooting--faq)

---

</div>

## 🎯 What Is This?

**n8n MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the complete **n8n REST API** as **54 structured tools** that AI agents can call directly.

Connect it to **Claude Desktop**, **Cursor AI**, **Windsurf**, **VS Code**, or any MCP-compatible client — and your AI can autonomously:

- 🔨 **Build and deploy** production-ready n8n workflows from scratch
- 🔍 **Debug failed executions** by inspecting node-by-node input/output data
- 🔐 **Manage credentials** securely (secrets are never exposed in responses)
- 📊 **Generate analytics** — success rates, avg duration, error trends
- 🛡️ **Run security audits** — detect unprotected webhooks, risky nodes, CVE exposure
- 📁 **Organize projects** and manage team member access
- 🔄 **Sync Git repositories** via source control pull
- 👥 **Administer users** — invite, remove, change roles

---

## ✨ Key Features

| | Feature | Details |
|:---:|:---|:---|
| 🤖 | **54 Production-Ready Tools** | Full coverage of n8n REST API v1 — Workflows, Executions, Credentials, Tags, Variables, Projects, Security Audit, Source Control, Users |
| 🧠 | **AI-Optimized Descriptions** | Every tool has rich, actionable descriptions that help Claude choose the right tool automatically |
| ⚙️ | **Typed Workflow Settings** | Strongly-typed `settings` schema: timezone, errorWorkflow, callerPolicy, executionTimeout, saveDataSuccessExecution, and more |
| 📦 | **23-Node Template Library** | Built-in JSON snippets for Webhooks, Schedule, HTTP Request, Code, Switch, OpenAI, Slack, Gmail, Telegram, Postgres, MySQL, and more |
| 📊 | **Execution Analytics** | Success rate, avg/min/max duration, status breakdown across N recent executions |
| 🗑️ | **Bulk Delete w/ Dry-Run** | Preview exactly what will be deleted before committing — safety-first |
| 🛡️ | **Security Audit** | Severity-ranked report (Critical/High/Medium/Low) via `POST /api/v1/audit` |
| 🔄 | **Git Source Control** | Pull from connected Git repos, check sync status and branch info |
| 🔁 | **Auto Retry + Backoff** | 3 automatic retries with exponential backoff on 429/5xx errors |
| 🐳 | **Docker Multi-Stage** | Optimized production image — secrets injected at runtime, never baked in |
| ⚡ | **Fast Build** | `esbuild` compiles the entire server in < 400ms |

---

## 📐 Architecture

```mermaid
flowchart LR
    subgraph AI["🤖 AI Clients (MCP)"]
        A[Claude Desktop]
        B[Cursor AI]
        C[Windsurf / VS Code]
        D[Any MCP Client]
    end

    subgraph MCP["⚙️ n8n MCP Server v2.0.0"]
        direction TB
        E[54 Registered Tools]
        F[Zod Schema Validation]
        G[Axios Client\nRetry + Tracing]
    end

    subgraph N8N["🔧 n8n Instance"]
        direction TB
        H[(Workflows Engine)]
        I[(Executions Log)]
        J[(Credentials Store)]
        K[(Variables / Tags)]
        L[(Projects / Users)]
        M[(Git Source Control)]
    end

    A <-->|stdio Transport| E
    B <-->|stdio Transport| E
    C <-->|stdio Transport| E
    D <-->|stdio Transport| E

    E --> F --> G
    G <-->|"n8n REST API v1\nX-N8N-API-KEY"| H
    G <-->|REST| I
    G <-->|REST| J
    G <-->|REST| K
    G <-->|REST| L
    G <-->|REST| M
```

---

## 🚀 Quick Start

### Prerequisites

- **Node.js** `v18+`
- **n8n instance** — self-hosted (`http://localhost:5678`) or [n8n Cloud](https://app.n8n.cloud)
- **n8n API Key** → `n8n Settings → API → Create API Key`

### 1. Clone & Install

```bash
git clone https://github.com/SohailShabbir867/n8n_mcp.git
cd n8n_mcp
npm install
```

### 2. Configure Environment

```bash
cp .env.example .env
```

Edit `.env`:
```env
# Required
N8N_BASE_URL=http://localhost:5678
N8N_API_KEY=your_n8n_api_key_here

# Optional (default: v1)
N8N_API_VERSION=v1
```

### 3. Build

```bash
npm run build
```

✅ You'll see: `dist/index.js  1.3mb  Done in ~400ms`

---

## 💻 Client Setup: Claude & Cursor & Windsurf

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or  
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["C:/path/to/n8n_mcp/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_n8n_api_key_here"
      }
    }
  }
}
```

### Cursor AI / Windsurf

Go to **Settings → MCP Servers → Add Server**:

```json
{
  "n8n": {
    "command": "node",
    "args": ["C:/path/to/n8n_mcp/dist/index.js"],
    "env": {
      "N8N_BASE_URL": "http://localhost:5678",
      "N8N_API_KEY": "your_n8n_api_key_here"
    }
  }
}
```

### Via Docker (recommended for production)

```json
{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "N8N_BASE_URL=http://localhost:5678",
        "-e", "N8N_API_KEY=your_key",
        "n8n-mcp:2.0.0"
      ]
    }
  }
}
```

---

## 🐳 Docker

### Build Locally

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

### Run with env file (recommended)

```bash
docker run --rm -i --env-file .env n8n-mcp:2.0.0
```

### Run with inline env vars (PowerShell)

```powershell
docker run --rm -i `
  -e N8N_BASE_URL=https://your-n8n.com `
  -e N8N_API_KEY=your_key_here `
  n8n-mcp:2.0.0
```

> ✅ The Dockerfile uses **multi-stage builds** — your `.env` secrets are **never baked into the image**.

---

## 🛠️ Tool Reference (54 Tools)

### 📋 Workflows — 14 Tools

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `list_workflows` | List workflows with filters | `active`, `tags`, `name`, `projectId`, `limit` |
| `get_workflow` | Get full workflow detail | `id`, `excludePinData` |
| `create_workflow` | Create a new workflow | `name`, `nodes`, `connections`, `settings`, `activate`, `pinData` |
| `update_workflow` | Partial update — any field | `id`, `name`, `nodes`, `settings`, `active`, `pinData` |
| `delete_workflow` | Permanently delete | `id` |
| `activate_workflow` | Enable trigger | `id` |
| `deactivate_workflow` | Pause trigger | `id` |
| `duplicate_workflow` | Clone a workflow | `id`, `name`, `activate` |
| `export_workflow` | Export as portable JSON | `id`, `includePinData` |
| `import_workflow` | Import from JSON string | `workflowJson`, `activate`, `projectId` |
| `search_workflows` | Advanced search + date filters | `query`, `active`, `tags`, `createdAfter`, `createdBefore` |
| `get_workflow_stats` | Execution analytics per workflow | `id`, `last` (N executions) |
| `transfer_workflow` | Move to another project | `id`, `destinationProjectId` |
| `list_common_nodes` | 23 copy-paste node templates | `category`, `search` |

<details>
<summary><b>⚙️ Full Workflow Settings Schema</b></summary>

When creating or updating a workflow, the `settings` object supports:

| Setting | Type | Description |
|:---|:---|:---|
| `executionOrder` | `"v0"` \| `"v1"` | Execution strategy (use `v1`) |
| `timezone` | `string` | e.g. `"America/New_York"`, `"Asia/Karachi"` |
| `saveManualExecutions` | `boolean` | Save manual test runs |
| `saveExecutionProgress` | `boolean` | Save progress for long-running workflows |
| `saveDataSuccessExecution` | `"all"` \| `"none"` | Save output on success |
| `saveDataErrorExecution` | `"all"` \| `"none"` | Save output on error |
| `executionTimeout` | `number` | Max runtime in seconds (`-1` = unlimited) |
| `errorWorkflow` | `string` | Workflow ID to call on failure |
| `callerPolicy` | `"any"` \| `"none"` \| `"workflowsFromAList"` \| `"workflowsFromSameOwner"` | Who can call this workflow |
| `callerIds` | `string` | Comma-separated workflow IDs (for `workflowsFromAList`) |

</details>

---

### ⚡ Executions — 8 Tools

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `list_executions` | List with filters + date range | `workflowId`, `status`, `startedAfter`, `startedBefore`, `limit` |
| `get_execution` | Node-by-node detail + summary | `id`, `includeData` |
| `delete_execution` | Delete execution record | `id` |
| `run_workflow` | Manually trigger | `id`, `data`, `startNode`, `destinationNode` |
| `retry_execution` | Retry a failed run | `id`, `loadWorkflowFromDb` |
| `stop_execution` | Cancel running execution | `id` |
| `get_execution_summary` | Aggregated stats for a workflow | `workflowId`, `limit` |
| `bulk_delete_executions` | Safe bulk delete with dry-run | `workflowId`, `status`, `startedBefore`, `dryRun`, `maxDelete` |

---

### 🔑 Credentials — 6 Tools

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `list_credentials` | List all credential metadata | `name`, `limit` |
| `get_credential` | Inspect type & dates (masked) | `id` |
| `create_credential` | Create new credential | `name`, `type`, `data`, `projectId` |
| `update_credential` | Update name/type/data | `id`, `name`, `type`, `data` |
| `delete_credential` | Permanently delete | `id` |
| `list_credential_types` | Find type IDs (e.g. `openAiApi`) | `search`, `limit` |

---

### 🏷️ Tags — 4 Tools

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `list_tags` | List all tags | `limit`, `cursor` |
| `create_tag` | Create a new tag | `name` |
| `update_tag` | Rename a tag | `id`, `name` |
| `delete_tag` | Delete a tag | `id` |

---

### 🔧 Variables — 4 Tools

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `list_variables` | List instance variables | `limit`, `cursor` |
| `create_variable` | Create `$vars.KEY` | `key`, `value` |
| `update_variable` | Update key or value | `id`, `key`, `value` |
| `delete_variable` | Delete a variable | `id` |

---

### 🛡️ Security Audit — 1 Tool

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `run_security_audit` | Full security report with severity ranking | `categories`, `daysAbandonedWorkflow` |

**Categories:** `credentials` · `database` · `filesystem` · `instance` · `nodes`

**Detects:** Unprotected webhooks · Unused credentials · Risky community nodes · Outdated n8n version · Dangerous security configs · Abandoned workflows

---

### 📁 Projects — 7 Tools *(Enterprise/Team)*

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `list_projects` | List all projects | `limit`, `cursor` |
| `get_project` | Get project details | `id` |
| `create_project` | Create team/personal project | `name`, `type` |
| `update_project` | Rename project | `id`, `name` |
| `delete_project` | Delete (with migration option) | `id`, `migrateToProject` |
| `add_project_member` | Add user with role | `projectId`, `userId`, `role` |
| `remove_project_member` | Remove user from project | `projectId`, `userId` |

**Roles:** `project:admin` · `project:editor` · `project:viewer`

---

### 🔄 Source Control — 2 Tools *(Enterprise Git)*

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `pull_from_git` | Pull latest from Git repo | `force`, `variables` |
| `get_source_control_status` | View repo, branch, SSH key status | — |

---

### 👥 System & Users — 8 Tools

| Tool | Description | Key Parameters |
|:---|:---|:---|
| `test_connection` | Health check + latency + version | — |
| `get_instance_info` | n8n version, DB type, license, plan | — |
| `list_users` | List all users with role filter | `role`, `limit` |
| `get_user` | User details by ID or email | `id` |
| `invite_user` | Send invite + get invite link | `email`, `role` |
| `delete_user` | Remove user (with workflow transfer) | `id`, `migrateWorkflowsTo` |
| `change_user_role` | Change global role | `id`, `role` |

**Global Roles:** `global:owner` · `global:admin` · `global:member`

---

## 💡 Example AI Prompts

Copy these directly into Claude or Cursor:

```
Test the connection to my n8n server and show me the version and API latency.
```

```
Create an active workflow called "Daily Sales Report" with a Schedule Trigger 
at 9am every weekday, a Postgres node to fetch yesterday's sales, 
and a Slack node to post the summary to #sales-team.
```

```
Find all failed executions from the last 7 days for workflow ID "abc123", 
inspect the first one to see which node failed, then retry it.
```

```
Run a security audit on my n8n instance and give me a prioritized action 
plan to fix all Critical and High severity risks.
```

```
List all my workflows and show me stats (success rate, avg duration) 
for the top 5 most-executed ones.
```

```
Bulk delete all "error" executions older than 30 days for workflow "xyz" — 
first show me a dry run, then confirm deletion.
```

```
Invite user@company.com to n8n as a global:member and add them to 
project "Marketing Automations" as a project:editor.
```

```
Export workflow "Weekly Newsletter" as JSON, then duplicate it and rename 
the copy "Weekly Newsletter — TEST" and keep it deactivated.
```

---

## 🔍 Troubleshooting & FAQ

<details>
<summary><b>❓ "N8N_API_KEY environment variable is missing"</b></summary>
<br/>
Create a <code>.env</code> file in the project root or pass the key via your MCP client config's <code>env</code> block. Get your API key from <b>n8n → Settings → API → Create API Key</b>.
</details>

<details>
<summary><b>❓ Can I use this with n8n Cloud?</b></summary>
<br/>
Yes! Set <code>N8N_BASE_URL=https://your-instance.app.n8n.cloud</code> and use your Cloud API key. Everything works identically.
</details>

<details>
<summary><b>❓ Why does bulk_delete_executions default to dry-run?</b></summary>
<br/>
Safety by design. The dry run shows you exactly which executions match your filters before any deletion occurs. Always confirm the list looks correct before setting <code>dryRun=false</code>.
</details>

<details>
<summary><b>❓ Source control / Projects tools return 404</b></summary>
<br/>
Source Control (Git integration) and Projects require <b>n8n Business or Enterprise</b> plan. The tools handle this gracefully and return a helpful setup message instead of crashing.
</details>

<details>
<summary><b>❓ How do I update to a new version?</b></summary>
<br/>

```bash
git pull origin main
npm install
npm run build
# Then restart your MCP client
```

</details>

<details>
<summary><b>❓ PowerShell multiline docker run syntax</b></summary>
<br/>
Use backtick <code>`</code> instead of backslash <code>\</code> for line continuation in PowerShell:

```powershell
docker run --rm -i `
  -e N8N_BASE_URL=https://your-n8n.com `
  -e N8N_API_KEY=your_key `
  n8n-mcp:2.0.0
```

</details>

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. **Fork** the repository
2. **Create** your branch: `git checkout -b feature/my-feature`
3. **Commit**: `git commit -m 'feat: add my feature'`
4. **Push**: `git push origin feature/my-feature`
5. Open a **Pull Request**

Please follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages.

---

## 📜 License

Distributed under the **MIT License** — see [`LICENSE`](LICENSE) for details.

---

<!-- SEO Keywords: n8n MCP server, n8n Model Context Protocol, n8n Claude Desktop integration, n8n Cursor AI, n8n automation AI, n8n REST API MCP, n8n workflow builder AI, n8n execution debugger, n8n credential manager MCP, n8n self-hosted automation, n8n cloud API, Claude Desktop n8n, MCP server TypeScript, n8n security audit, n8n project management API, n8n source control, n8n AI agent tools, n8n workflow statistics, n8n bulk delete executions, n8n invite users API -->

<div align="center">

<br/>

Made with ❤️ by [Sohail Shabbir](https://github.com/SohailShabbir867)

**⭐ Star this repo if it saves you time!**

[![GitHub stars](https://img.shields.io/github/stars/SohailShabbir867/n8n_mcp?style=social)](https://github.com/SohailShabbir867/n8n_mcp/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/SohailShabbir867/n8n_mcp?style=social)](https://github.com/SohailShabbir867/n8n_mcp/fork)

</div>