n8n-mcp

The most comprehensive MCP server for n8n — 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

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

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)

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

cp .env.example .env

Edit .env with your values:

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

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):

{
  "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)

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

Or add to your project's .mcp.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):

MCP Resources

Browsable read-only views of your n8n data:

MCP Prompts

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

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

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

# Run tests
pytest -v

# Lint
ruff check src/ tests/

# Type check
mypy src/

License

MIT