# n8n-mcp

[![CI](https://github.com/Siddharth0903/n8n-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Siddharth0903/n8n-mcp/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

The most comprehensive [MCP](https://modelcontextprotocol.io) server for [n8n](https://n8n.io) — **43 tools**, **8 prompt templates**, and **6 browsable resources** covering the entire n8n REST API surface. The first Python implementation.

Give Claude (or any MCP-compatible AI client) full control over your n8n instance: build workflows, run executions, manage credentials, query data tables, run security audits — all through natural language.

## Highlights

- **43 MCP Tools** — Full CRUD for workflows, executions, credentials, tags, variables, and data tables, plus admin operations like security audits and API capability discovery
- **Double-Validated Workflow Creation** — `create_and_validate_workflow` runs a 6-phase pipeline: create, structural read-back check, two execution passes, consistency comparison, and a PASS/FAIL verdict
- **Write Safety by Default** — All mutating operations are disabled unless you explicitly opt in with `N8N_MCP_WRITE_MODE=true`
- **8 Guided Prompt Templates** — Multi-step AI workflows for debugging, health checks, security reviews, workflow creation with full testing, and more
- **Async & Paginated** — Built on `httpx` with cursor-based auto-pagination and configurable timeouts

## Features

| Category | Tools |
|---|---|
| **Workflows** (13) | `list_workflows`, `get_workflow`, `create_workflow`, `update_workflow`, `delete_workflow`, `activate_workflow`, `deactivate_workflow`, `get_workflow_version`, `get_workflow_tags`, `update_workflow_tags`, `execute_workflow`, `trigger_webhook_test`, `create_and_validate_workflow` |
| **Executions** (8) | `list_executions`, `get_execution`, `delete_execution`, `retry_execution`, `stop_execution`, `stop_many_executions`, `get_execution_tags`, `update_execution_tags` |
| **Credentials** (5) | `list_credentials`, `create_credential`, `update_credential`, `delete_credential`, `get_credential_schema` |
| **Tags** (5) | `list_tags`, `get_tag`, `create_tag`, `update_tag`, `delete_tag` |
| **Variables** (4) | `list_variables`, `create_variable`, `update_variable`, `delete_variable` |
| **Data Tables** (5) | `list_data_tables`, `get_data_table`, `create_data_table`, `query_table_rows`, `insert_table_rows` |
| **Admin** (3) | `generate_audit`, `discover_capabilities`, `source_control_pull` |

Plus **8 MCP prompt templates** and **6 browsable resources**.

## Prerequisites

- **Python 3.10+**
- **n8n instance** — local (Docker) or remote (cloud-hosted)
- **n8n API key** — generated from n8n Settings

## Quick Start

### 1. Clone and install

```bash
git clone https://github.com/Siddharth0903/n8n-mcp.git
cd n8n-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 2. Start n8n (if you don't have one running)

```bash
docker compose up -d
```

This starts n8n with PostgreSQL at `http://localhost:5678`.

### 3. Get your n8n API key

1. Open `http://localhost:5678` in your browser
2. Complete the initial setup if this is a fresh instance
3. Go to **Settings** (gear icon) > **n8n API**
4. Click **Create an API key**
5. Copy the key

### 4. Configure environment

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

Edit `.env` with your values:

```bash
N8N_MCP_BASE_URL=http://localhost:5678   # Your n8n URL
N8N_MCP_API_KEY=your-api-key-here        # The API key from step 3
N8N_MCP_WRITE_MODE=false                 # Set to 'true' to enable create/update/delete
```

### 5. Run the server

```bash
n8n-mcp
```

The MCP server is now running over stdio, ready for any MCP client to connect.

## Client Integration

### Claude Desktop

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

```json
{
  "mcpServers": {
    "n8n": {
      "command": "/absolute/path/to/your/.venv/bin/n8n-mcp",
      "env": {
        "N8N_MCP_BASE_URL": "http://localhost:5678",
        "N8N_MCP_API_KEY": "your-api-key-here",
        "N8N_MCP_WRITE_MODE": "true"
      }
    }
  }
}
```

> **Tip:** Use the full absolute path to the `n8n-mcp` binary inside your virtualenv.

### Claude Code (CLI)

```bash
claude mcp add n8n -- /absolute/path/to/your/.venv/bin/n8n-mcp
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "n8n": {
      "command": "/absolute/path/to/your/.venv/bin/n8n-mcp",
      "env": {
        "N8N_MCP_BASE_URL": "http://localhost:5678",
        "N8N_MCP_API_KEY": "your-api-key-here",
        "N8N_MCP_WRITE_MODE": "true"
      }
    }
  }
}
```

### Any MCP Client

n8n-mcp uses the standard MCP stdio transport. Any MCP-compatible client can connect by launching the `n8n-mcp` binary.

## Configuration

All settings are configured via environment variables (or `.env` file):

| Variable | Default | Description |
|---|---|---|
| `N8N_MCP_BASE_URL` | `http://localhost:5678` | n8n instance URL |
| `N8N_MCP_API_KEY` | *(required)* | n8n API key |
| `N8N_MCP_WRITE_MODE` | `false` | Enable create/update/delete operations |
| `N8N_MCP_TIMEOUT` | `30` | HTTP request timeout in seconds |
| `N8N_MCP_MAX_ITEMS` | `100` | Default pagination limit |
| `N8N_MCP_WEBHOOK_USERNAME` | *(optional)* | Basic Auth username for webhook triggers |
| `N8N_MCP_WEBHOOK_PASSWORD` | *(optional)* | Basic Auth password for webhook triggers |

## MCP Resources

Browsable read-only views of your n8n data:

| URI | Description |
|---|---|
| `n8n://workflows` | All workflows with name, ID, active status, and tags |
| `n8n://workflows/{id}` | Full workflow structure including nodes and connections |
| `n8n://workflows/{id}/executions` | Execution history for a specific workflow |
| `n8n://executions/{id}` | Detailed execution data with per-node results |
| `n8n://variables` | All instance variables |
| `n8n://data-tables` | All data tables with schemas |

## MCP Prompts

Guided multi-step templates that walk the AI through complex operations:

| Prompt | Description |
|---|---|
| `debug_workflow` | Step-by-step guide to diagnose and fix a failing workflow |
| `workflow_health_check` | Audit all workflows for health issues and security risks |
| `execution_report` | Generate execution analytics and success rate reports |
| `find_workflow` | Find a workflow matching a natural language description |
| `data_audit` | Analyze a data table's structure, quality, and contents |
| `security_review` | Full security review of the n8n instance |
| `create_and_test_workflow` | Create a new workflow with 6-phase validation and delivery checklist |
| `validate_workflow` | End-to-end validation of an existing workflow: structure, credentials, history, and live test |

## Safety

- **Write mode is OFF by default** — only read operations work until you explicitly set `N8N_MCP_WRITE_MODE=true`
- **Credential secrets are never exposed** — the n8n API only returns metadata, never secret values
- **Webhook path validation** — prevents path traversal and SSRF attacks
- **Structured error responses** — every error returns actionable JSON with hints, not raw exceptions
- **Request timeouts** — configurable timeouts prevent hanging connections

## Architecture

```
Claude / MCP Client
        |
        v
  +-----------+
  |  n8n-mcp  |  FastMCP server (Python, async)
  |           |
  | 43 tools  |  Workflows, Executions, Credentials,
  | 6 rsrc    |  Tags, Variables, Data Tables, Admin
  | 8 prompts |
  +-----+-----+
        | httpx (async, paginated)
        v
  +-----------+
  |  n8n API  |  REST /api/v1
  +-----+-----+
        |
        v
  +-----------+
  | Workflows |
  |  & Data   |
  +-----------+
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Lint
ruff check src/ tests/

# Type check
mypy src/
```

## License

[MIT](LICENSE)