n8n-mcp-py

A Python MCP (Model Context Protocol) server that wraps the n8n public REST API, exposing 40 tools any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Windsurf) can call.

n8n ships its own MCP server, but in self-hosted v2.8.x it depends on a per-workflow availableInMCP toggle that silently fails to persist. It's also limited to read + execute on opt-in workflows — you can't create, update, or manage executions from an MCP client.

This server uses n8n's public REST API (no opt-in flags, no UI bug), giving full coverage on workflows, executions, credentials, tags, variables, users, projects, source control, and audit.

All mutating tools accept dry_run=True to preview the request without calling the API. Destructive tools carry MCP destructiveHint annotations so clients can surface confirmation prompts.

pip install n8n-mcp-py

Or from source:

git clone https://github.com/CKSoupen/n8n-mcp-python
cd n8n-mcp-python
pip install -e ".[dev]"

Set two environment variables — either in your shell, in a .env file (see .env.example), or via your MCP client's config:

N8N_BASE_URL=https://your-n8n.example.com
N8N_API_KEY=eyJhbGc...   # public-api JWT, from n8n Settings → API

Optional knobs:

N8N_TIMEOUT_SECONDS=30
N8N_USER_AGENT=Mozilla/5.0 (compatible; n8n-mcp-py)
N8N_VERIFY_SSL=true

Cloudflare note: the default User-Agent is browser-like because many self-hosted n8n instances sit behind Cloudflare, whose default WAF rules can block bare python/requests clients with a 1010 error.

claude mcp add n8n-py -- n8n-mcp

Then put N8N_BASE_URL and N8N_API_KEY in ~/.claude.env or set them in your shell profile.

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

{
  "mcpServers": {
    "n8n-py": {
      "command": "n8n-mcp",
      "env": {
        "N8N_BASE_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "eyJhbGc..."
      }
    }
  }
}

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "n8n-py": {
      "command": "n8n-mcp",
      "env": {
        "N8N_BASE_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "eyJhbGc..."
      }
    }
  }
}

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "n8n-py": {
      "command": "n8n-mcp",
      "env": {
        "N8N_BASE_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "eyJhbGc..."
      }
    }
  }
}

• Build plan / phases
• Prior-art research
• Issues

# install
pip install -e ".[dev]"

# lint
ruff check src tests

# test
pytest -q

# run the server locally (stdio) — useful for ad-hoc debugging
N8N_BASE_URL=https://... N8N_API_KEY=... n8n-mcp

MIT