c4e1c62882
Fix inconsistent line endings across all project files for cross-environment consistency. Add complete unit test suite covering core utilities, API routes, and server services. Add Playwright E2E test setup with smoke, auth, and agent API tests. Update all project configuration files to match standardized formatting. Fix MCP API error handling to properly propagate HTTP status codes and use correct JSON-RPC error codes. Add VSCode workspace configuration, extensions, and example MCP config files. Update .gitignore to exclude new test and build artifacts.
114 lines
6.4 KiB
Markdown
114 lines
6.4 KiB
Markdown
# n8n-MCP Setup
|
|
|
|
[`.mcp.json`](../.mcp.json) wires the [n8n MCP server](https://docs.n8n.io/advanced-ai/accessing-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
|
|
|
|
```bash
|
|
# 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](https://jwt.io) to confirm).
|
|
|
|
## Step 3 — Update `.mcp.json`
|
|
|
|
Open [`.mcp.json`](../.mcp.json) (this file is gitignored — see [Security notes](#security-notes)) and set the `url` and `Authorization` header to your instance + key:
|
|
|
|
```json
|
|
{
|
|
"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`](../.mcp.example.json) — copy it to `.mcp.json` and fill in your values:
|
|
|
|
```bash
|
|
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](#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`](../.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.
|