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

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

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

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

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

# Run tests
pytest -v

# Lint
ruff check src/ tests/

# Type check
mypy src/

License

MIT