WFDASH-WEBAPP/docs/n8n-mcp-setup.md

n8n-MCP Setup

.mcp.json wires the n8n MCP server into Claude Code for this project. n8n ships with a built-in HTTP MCP endpoint (/mcp-server/http), so there's no extra package to install — just point Claude Code at the URL with a JWT.

Once it's running, you can ask Claude to "create an n8n workflow that ..." and the model can drive n8n directly (create / update / activate workflows, list executions, run nodes, etc.) through MCP tools.

---

What it does

The n8n MCP server exposes the n8n workflow API as MCP tools. From inside Claude Code you get tools roughly equivalent to:

• search_workflows, get_workflow, create_workflow, update_workflow, delete_workflow
• activate_workflow, deactivate_workflow
• list_executions, get_execution
• test_workflow (run a workflow once without activating it)
• SDK/reference tools for building workflow code programmatically

The full list is returned by the tools/list JSON-RPC method on the MCP endpoint.

Prerequisites

1. n8n running somewhere the machine running Claude Code can reach (locally, in Docker, or hosted on n8n.cloud / a custom URL).
2. A MCP-server API key from n8n. Important: this is a different credential from the regular REST API key — it has audience mcp-server-api, not public-api. Using the wrong one returns 401.

Step 1 — Verify the MCP endpoint is reachable

# Replace <host> with your n8n host (no trailing slash on the URL)
curl -s -X POST "https://<host>/mcp-server/http" \
  -H "Authorization: Bearer <your-mcp-jwt>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-test","version":"0"}}}'

A healthy response looks like:

event: message
data: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true},...},"serverInfo":{"name":"n8n MCP Server","version":"1.1.0"},...}}

401 means the JWT is wrong or has the wrong audience. 404 usually means the host is reachable but n8n is not at that path.

Step 2 — Get a MCP-server API key

In the n8n UI:

1. Click your user icon (top right) → Settings → API
2. Click Create an API key
3. Give it a label (e.g. claude-code-mcp)
4. Copy the key — n8n only shows it once. The token's aud claim must be mcp-server-api (decode the JWT at jwt.io to confirm).

Step 3 — Update .mcp.json

Open .mcp.json (this file is gitignored — see Security notes) and set the url and Authorization header to your instance + key:

{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "https://<your-n8n-host>/mcp-server/http",
      "headers": {
        "Authorization": "Bearer <your-n8n-mcp-jwt-here>"
      }
    }
  }
}

A committed template (no real key) lives at .mcp.example.json — copy it to .mcp.json and fill in your values:

cp .mcp.example.json .mcp.json
$EDITOR .mcp.json

If your n8n is on a self-signed cert or behind a private CA, add "NODE_EXTRA_CA_CERTS": "/path/to/ca.pem" to the server env block (this only works for stdio servers, so prefer fixing the cert chain if you can).

Step 4 — Restart Claude Code

The MCP server is started by Claude Code when the session boots. Quit and reopen Claude Code in this project so it picks up .mcp.json. You should see n8n-mcp listed in the MCP servers status (or invoke /mcp to verify).

Step 5 — Sanity-check

Ask Claude: "List my n8n workflows". If you have none yet it should return an empty list. If it errors, jump to Troubleshooting.

Connecting n8n to WFDASH

Once n8n can talk to the MCP server in Claude Code, the natural next step is to make n8n talk to WFDASH:

• n8n as MCP client of WFDASH: in any n8n workflow, add the MCP Client Tool node and point it at http://localhost:3000/api/mcp with the bearer token from your WFDASH AGENT_API_KEY. You get orders.list, orders.create_from_quote, collection_pool.list, and order_items.update_status as drag-and-drop tools.
• WFDASH → n8n via webhooks: n8n can expose a webhook URL; WFDASH's REST API can be extended (or a small script can call n8n) to trigger workflows on events (e.g. "quote approved" → kick off an order-creation workflow).
• Cron in n8n: schedule a daily digest workflow that calls orders.list and posts to Slack / email.

Troubleshooting

Symptom	Cause / fix
401 Unauthorized from the MCP endpoint	JWT has the wrong audience. Decode it at jwt.io — you want aud: mcp-server-api, not public-api. Re-create the key in n8n with the right audience, or use a different key.
404 Not Found on /mcp-server/http	n8n is reachable but the MCP server route is missing. Make sure you're on a recent n8n version (the built-in MCP server shipped in 1.x).
MCP tools not showing up in Claude Code	You need to restart Claude Code after editing .mcp.json. Use /mcp to list loaded servers.
ECONNREFUSED / connection timeout	n8n isn't reachable from where Claude Code is running. curl the URL manually first to confirm DNS + port.
self signed certificate errors	If n8n is behind TLS with a private CA, set NODE_EXTRA_CA_CERTS in the server's env block (stdio servers only). For HTTP servers, fix the CA chain on the client or n8n side.
tools/list returns empty []	n8n is up and auth works, but there are no workflows yet (or no permission to see them). Create a test workflow in the n8n UI and re-run.

Security notes

• .mcp.json is gitignored. The real JWT lives only in your local copy. The committed template is .mcp.example.json with placeholder values.
• If you ever accidentally commit .mcp.json, rotate the n8n API key immediately — anyone with the JWT can read and modify every workflow in the instance.
• Prefer a scoped / read-only key when you don't need write access. n8n currently issues a single key per user, so rotate the existing one and re-issue a new one if you need different scopes.
• Treat the n8n API key like any other long-lived secret — it doesn't expire on its own, set a calendar reminder to rotate.