n8n Deploy

Manage n8n workflows directly from Claude Code via REST API. No MCP server, no Python packages, no dependencies — just curl.

Prerequisites

Two environment variables must be set (in shell profile, .env, or exported):

export N8N_API_URL="https://your-n8n.example.com"   # No trailing slash
export N8N_API_KEY="your-api-key-here"               # Settings > API > Create API Key

How to get your API key:

1. Open your n8n instance
2. Go to Settings > API (or n8n-url/settings/api)
3. Click Create API Key
4. Copy the key and set N8N_API_KEY

Commands

Check connection

curl -sf -o /dev/null -w "%{http_code}" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows?limit=1"

200 = connected. 401 = bad API key. Connection refused = wrong URL.

List all workflows

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows" | python3 -m json.tool

Parse the response to show: id, name, active, updatedAt.

Import a workflow from JSON file

curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d @/path/to/workflow.json \
  "$N8N_API_URL/api/v1/workflows"

Returns the created workflow object including its id. Save this ID for activate/run.

Pre-import checks:

1. Read the JSON file first and verify it has name, nodes, connections keys
2. Warn if any node contains credentials — these won't transfer and must be set up in n8n UI
3. Warn if the workflow name already exists (list first, check for duplicates)

Activate a workflow

curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows/{id}/activate"

Deactivate a workflow

curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows/{id}/deactivate"

Run a workflow manually

curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$N8N_API_URL/api/v1/workflows/{id}/run"

To pass input data:

curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"coin": "BTC"}}' \
  "$N8N_API_URL/api/v1/workflows/{id}/run"

Update a workflow

curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d @/path/to/updated-workflow.json \
  "$N8N_API_URL/api/v1/workflows/{id}"

Delete a workflow

DESTRUCTIVE — always confirm with the user before executing.

curl -s -X DELETE \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/workflows/{id}"

Get execution history

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_URL/api/v1/executions?workflowId={id}&limit=10"

Security Rules

1. Never echo or log $N8N_API_KEY — use it only in curl headers
2. Never expose credentials in workflow JSON — warn if credentials keys are found in nodes
3. Always use HTTPS — refuse to call HTTP endpoints (warn the user)
4. Delete requires confirmation — always ask before DELETE requests
5. Validate JSON before import — read the file first, check for required keys
6. Don't store API keys in files — always read from environment variables

Error Handling

Typical Workflow

1. Import: Read JSON file > pre-check > POST to create > get workflow ID
2. Activate: POST activate with the returned ID
3. Verify: GET the workflow to confirm active: true
4. Monitor: Check execution history after first scheduled run

Reference Files

For full API endpoint details, see references/api-reference.md (loaded on demand).

Credential Handling

Credentials (API keys, OAuth tokens) stored in n8n are not exported in workflow JSON. After importing a workflow, the user must:

1. Open the workflow in n8n UI
2. Click on each node that requires credentials
3. Select or create the appropriate credential

Always remind the user about this after a successful import.