N8n

n8n — operate a live instance over its REST API and MCP

You already have a workflow design — the trigger→steps→error shape and the importable JSON, which is automation-flows' job and this skill does not re-teach it. This skill is the operate half: push that JSON into a running n8n, validate it, test it, flip it live, watch its executions, and tear it down safely — all without touching the UI. n8n has the richest programmatic story of the no-code platforms: a first-party REST API plus a mature MCP server, both hitting the same instance.

Connect first — REST API vs MCP

Two ways to drive the same instance. Pick by who is at the wheel.

Version reality (verify at author time — n8n moves fast):

• API base is {host}/api/v1. Self-host ships interactive Swagger at /api/v1/docs; cloud does not — on cloud, work from the docs.
• POST /workflows/{id}/execute (run-by-id) is recent (n8n PR #20234). Older instances lack it — there, the only programmatic run is POSTing to a Webhook node's URL.

.env

# host root only — you append /api/v1 for REST; n8n-mcp reads it whole
N8N_API_URL=https://your-instance.app.n8n.cloud   # or N8N_HOST for self-host, e.g. http://localhost:5678
N8N_API_KEY=n8n_api_...                            # Settings → n8n API → Create an API key

Never inline the key in a command that gets logged, and never put a node credential (Slack token, etc.) in the workflow payload — reference it by the n8n credential store id/name (see automation-flows' JSON schema). Full key-creation + self-host vs cloud + MCP install: references/auth-and-selfhost.md.

The payload you POST

The create/update body is exactly the automation-flows workflow JSON. Required top-level keys on create: name, nodes, connections, settings. Build it per ../automation-flows/references/n8n-workflow-json.md — non-empty nodes with one trigger, a wired connections map, settings.errorWorkflow, credentials referenced by store (never inlined).

Node/expression essentials (pointer, not a tutorial): node type is namespaced (n8n-nodes-base.webhook), typeVersion must match a node version installed on the target instance or activation/execution fails; field values use expressions like ={{ $json.email }} or ={{ $node["Webhook"].json.body.id }}. If you are hand-authoring nodes, let n8n-mcp's node-knowledge tools (search_nodes, get_node_essentials, validate_node_operation) fill in the exact property shapes rather than guessing — that is the single biggest reason to drive via MCP.

Dynamic lifecycle

create → validate → test → activate → manage → delete. A concrete sketch per step, curl and n8n-mcp side by side; every endpoint with pagination and scopes is in references/rest-api-cheatsheet.md.

1. Validate (do this BEFORE create)

REST has no validation endpoint — n8n only tells you at create/activate time. MCP does, so validate first when it is available:

n8n_validate_workflow   { "workflow": { …the full JSON… } }
n8n_autofix_workflow    { "workflow": { … } }   # repairs common structural errors, returns fixed JSON

2. Create

curl -sS -X POST "$N8N_API_URL/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
  -d @workflow.json          # body = { name, nodes, connections, settings }
# → returns the created workflow WITH its "id" — capture it for every step below

n8n_create_workflow     { "name": "...", "nodes": [ … ], "connections": { … }, "settings": { … } }

3. Test / dry-run

• No input needed → run by id (recent instances only): POST /workflows/{id}/execute.
• Needs input → the execute endpoint accepts none. Make the trigger a Webhook node and POST to its URL (test URL /webhook-test/<path> while "Listen for test event" is armed; production /webhook/<path> once active).

curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute" -H "X-N8N-API-KEY: $N8N_API_KEY"
curl -sS -X POST "$N8N_API_URL/webhook-test/my-path" -H "Content-Type: application/json" -d '{"foo":"bar"}'

n8n_test_workflow       { "id": "$ID" }

4. Activate — the step people miss

active (and tags) in the create/update body are read-only and silently ignored. Setting "active": true does nothing, which is why the workflow you just created never fires. You MUST call the separate endpoint:

curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/deactivate" -H "X-N8N-API-KEY: $N8N_API_KEY"

n8n-mcp deliberately does not expose activate/deactivate as tools (activation has live side effects). Check the current tool list; if absent, call the REST /activate endpoint as above.

5. Manage

curl -sS "$N8N_API_URL/api/v1/workflows?limit=50"      -H "X-N8N-API-KEY: $N8N_API_KEY"  # list (paginate via nextCursor)
curl -sS "$N8N_API_URL/api/v1/workflows/$ID"           -H "X-N8N-API-KEY: $N8N_API_KEY"  # get
curl -sS -X PUT "$N8N_API_URL/api/v1/workflows/$ID"    -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" -d @workflow.json                                  # FULL replace
curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&limit=20" -H "X-N8N-API-KEY: $N8N_API_KEY"

n8n_list_workflows {}        n8n_get_workflow { "id": "$ID" }        n8n_executions { "workflowId": "$ID" }
n8n_update_full_workflow    { "id": "$ID", "nodes": [ … ], "connections": { … } }   # replace everything
n8n_update_partial_workflow { "id": "$ID", "operations": [ … ] }                    # atomic diff — preferred
n8n_health_check {}          # confirm API reachable + which features the instance supports

PUT is a full replace — GET, mutate the whole object, PUT it back, or you drop the nodes you omitted. n8n-mcp's n8n_update_partial_workflow applies a targeted, atomic batch instead (safer).

6. Delete — irreversible

DELETE is a hard delete: no trash, no undo, so export the current JSON first, every time — this one is absolute because nothing downstream can recover the workflow if you skip it.

curl -sS "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY" > backup-$ID.json  # export FIRST
curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY"

n8n_get_workflow { "id": "$ID" }   →  save output  →  n8n_delete_workflow { "id": "$ID" }

The same applies to a full replace: export before PUT.

Governance

If you expose n8n-mcp to an agent, lock down destructive tools with the DISABLED_TOOLS env var (comma-separated), e.g. DISABLED_TOOLS=n8n_delete_workflow,n8n_update_full_workflow. Scope the API key itself too — n8n supports scoped keys (e.g. grant workflow:read without workflow:execute). Details in references/n8n-mcp-tools.md.

Anti-patterns

Route elsewhere