n8n-mcp-mini

An MCP server for working with n8n — modeled directly on czlonkowski/n8n-mcp. Two halves:

1. Node knowledge, always available: search and validate against 538 real n8n node schemas (all of n8n-nodes-base that could be extracted, plus the AI/LangChain node package), backed by SQLite + FTS5 — not a hand-picked sample, not hand-typed guesses.

2. Live n8n management, once you point it at a real instance: create, read, update, delete, and activate workflows; list/inspect executions; manage credentials; trigger a workflow via its webhook — all through n8n's actual public REST API.

How this compares to the real n8n-mcp

The two gaps that matter most — community nodes and the template library — are gaps in available data, not effort: neither is something this environment could fetch, verify, or safely fabricate. Everything else here is a real, working reimplementation of the same architecture, tested end to end.

Related MCP server: n8n-MCP

Install

cd n8n-mcp-mini
npm install

Requires Node.js 18+. better-sqlite3 downloads a prebuilt binary for your platform automatically on most systems. If npm install fails while building it, you likely need a C++ toolchain + Python (see better-sqlite3's install notes) — or just retry npm install, since the prebuilt-binary download occasionally fails transiently.

Run it standalone

npm start

Connect a real n8n instance (optional, enables the n8n_* tools)

1. In n8n: Settings → n8n API → Create an API key.

2. Set two environment variables when launching this server:

   • N8N_API_URL — e.g. https://your-instance.example.com/api/v1 (include the /api/v1)

   • N8N_API_KEY — the key you created

Without these, the node-knowledge tools work as normal and the n8n_* tools return a clear "not configured" error instead of failing mysteriously.

Register with Claude Desktop / Claude Code

{
  "mcpServers": {
    "n8n-mini": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp-mini/src/index.js"],
      "env": {
        "N8N_API_URL": "https://your-instance.example.com/api/v1",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

(Omit env entirely to run node-knowledge-only, no live instance.)

claude mcp add n8n-mini -- node /absolute/path/to/n8n-mcp-mini/src/index.js

Tools

Node knowledge (no setup required)

Live n8n management (needs N8N_API_URL + N8N_API_KEY)

A real gotcha this catches

n8n's Slack node requires channelId and other fields only once you've picked a resource/operation/select combination — supplying { resource: "message", operation: "post", text: "hi" } alone looks plausible but fails at runtime because select (which channel-lookup mode to use) was never set. validate_node catches this before you ever open n8n, by evaluating each property's displayOptions.show/hide rules against your config — the same mechanism n8n's own UI uses to decide which fields to show.

Workflow JSON shape

Validated against n8n's real JSON format — the same shape n8n's own API and UI use, so a validated workflow can go straight to n8n_create_workflow or be pasted into n8n's canvas:

{
  "name": "Notify on new signup",
  "nodes": [
    { "name": "Start", "type": "n8n-nodes-base.manualTrigger", "parameters": {} },
    { "name": "Fetch", "type": "n8n-nodes-base.httpRequest", "parameters": { "url": "https://api.example.com/signups/latest" } },
    { "name": "Notify", "type": "n8n-nodes-base.slack", "parameters": { "resource": "message", "operation": "post", "select": "channel", "channelId": "C0123", "text": "New signup!" } }
  ],
  "connections": {
    "Start": { "main": [[{ "node": "Fetch", "type": "main", "index": 0 }]] },
    "Fetch": { "main": [[{ "node": "Notify", "type": "main", "index": 0 }]] }
  },
  "settings": {}
}

Connections are keyed by node name (not id), and settings is required by n8n's API on create/update (the client auto-fills {} if you omit it).

n8n's real REST API, verified not guessed

src/n8nClient.js was written directly against n8n's published OpenAPI spec (n8n-io/n8n:packages/cli/src/public-api/v1/openapi.yml) — base path /api/v1, auth header X-N8N-API-KEY, exact request/response shapes per endpoint. It's tested against a local mock server that reproduces that same shape (test/mock_n8n_server.js), since no real n8n instance is available in this environment. One notable finding baked into the design: n8n's public API has no endpoint to execute a workflow on demand — the documented way is calling the workflow's own Webhook/Form trigger URL, which is what n8n_trigger_webhook does.

Data provenance

Node schemas are extracted directly from the real n8n-nodes-base@2.15.1 and @n8n/n8n-nodes-langchain@2.34.2 npm packages — not hand-typed guesses, and merged with n8n's own per-node categorization metadata (.node.json sidecar files: real categories, search aliases, docs URLs). See EXTRACTION.md for the full method, the handful of nodes that failed to extract and why, licensing notes, and exactly what's excluded (community nodes, template library) and why.

Tests

npm test
# or individually:
node test/unit.test.js         # store + validation logic, direct (11 tests)
node test/n8nClient.test.js    # REST client against a local mock n8n server (14 tests)
node test/mcp.smoke.js         # spawns the real server, drives all 27 tools over MCP/stdio