n8n-nodes-claude-sdk-agent

n8n community nodes for Claude Code via the official @anthropic-ai/claude-agent-sdk.

Includes:

Requirements

Install

n8n UI

Settings → Community Nodes → Install → n8n-nodes-claude-sdk-agent

Host dependencies (~/.n8n/nodes/package.json)

Community nodes must not bundle the SDK. Install alongside the node package in ~/.n8n/nodes (versions should match; check this package README or npm page for the recommended SDK release):

{
  "dependencies": {
    "n8n-nodes-claude-sdk-agent": "<version from n8n UI>",
    "@anthropic-ai/claude-agent-sdk": "<recommended SDK version>"
  },
  "optionalDependencies": {
    "@anthropic-ai/claude-agent-sdk-linux-x64": "<same as SDK>",
    "@anthropic-ai/claude-agent-sdk-linux-arm64": "<same as SDK>"
  }
}

Run npm install in ~/.n8n/nodes, then restart n8n.

Workflow topology

Webhook / Chat Trigger
        ↓
Claude Model Selector   ← each Profile binds a Claude Provider credential
        ↓  (json.claudeModelConfig)
Claude Agent            ← modelConfigSource: From Previous Node
        ↓
Response / SSE

Model Selector rules (example)

Claude Provider credential

Single credential type with Provider Type switching:

• Anthropic Direct — ANTHROPIC_API_KEY, dynamic /v1/models
• Anthropic Gateway — ANTHROPIC_BASE_URL + key (LiteLLM / Anthropic-compatible proxy)
• OpenAI Compatible Gateway — Upstream with only OpenAI Chat Completions; built-in anthropic-openai-shim handles protocol translation (no LiteLLM required)
• Bedrock / Vertex / Foundry / AWS Platform — env vars per Claude Code docs

Use Custom Model ID when the gateway does not expose /v1/models.

OpenAI Compatible Gateway

Claude Agent SDK sends Anthropic /v1/messages; many self-hosted or third-party gateways only accept OpenAI /v1/chat/completions. This package includes a lightweight shim — no LiteLLM needed.

1. Start the shim on the same host as n8n (one-time setup, recommend pm2):

# After installing the package under ~/.n8n/nodes:
node ~/.n8n/nodes/node_modules/n8n-nodes-claude-sdk-agent/scripts/anthropic-openai-shim.mjs

# Or from the dev directory: npm run shim
# Default: http://127.0.0.1:18789

pm2 example:

{
  name: 'claude-anthropic-openai-shim',
  script: 'scripts/anthropic-openai-shim.mjs',
  cwd: '/home/<user>/.n8n/nodes/node_modules/n8n-nodes-claude-sdk-agent',
  env: { CLAUDE_AGENT_SHIM_HOST: '127.0.0.1', CLAUDE_AGENT_SHIM_PORT: '18789' }
}

2. Configure the Claude Provider credential:

Credential test: ① probes upstream GET /models; ② sends a test message via shim POST /v1/messages. Both must pass.

Claude Agent node

Session continuation (1.6.0+)

Multi-turn context uses the Claude SDK session transcript on disk (~/.claude/projects/...). Redis stores { claudeSessionId, modelConfig } only.

Options → Session → Session Runtime

Output debug fields: sessionContinuation (new / resume / fork / setModel), sessionRuntime (sidecar / stateless / stateless-fallback), previousClaudeSessionId (when forked).

Agent Sidecar deployment

See services/claude-agent-sidecar/ecosystem.config.cjs. Default listen: 127.0.0.1:18790 (localhost only).

cd ~/.n8n/nodes && npm install n8n-nodes-claude-sdk-agent
cd node_modules/n8n-nodes-claude-sdk-agent
npm run build:sidecar
pm2 start services/claude-agent-sidecar/ecosystem.config.cjs --name claude-agent-sidecar
pm2 restart n8n

Sidecar .env (same Redis as Claude Agent node): REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, optional SIDECAR_IDLE_TIMEOUT_MS (default 30min), SIDECAR_MAX_SESSIONS (default 64).

In n8n: Claude Agent → Options → Session → Session Runtime = Sidecar, Sidecar URL = http://127.0.0.1:18790.

POC scripts:

npm run test:session          # continuation matrix
npm run poc:resume-fork       # Phase A (needs ANTHROPIC_API_KEY)
npm run sidecar               # start sidecar (terminal 1)
npm run poc:sidecar           # Phase B client (terminal 2)

Permission presets

Permission preset matrix

Workspace guidance: For mcp_skills_only / plan_only, set Skills Root to the skills directory only; do not mount source code repositories in Working Directories — these presets block file-read tools.

MCP Tool Filter (Options → MCP)

Claude vs Cursor (MCP permissions)

Official: MCP permissions — MCP requires allowedTools; acceptEdits does not auto-approve MCP.

Streaming output uses __claude__ JSON chunks.

Output fields

Local POC

npm install
ANTHROPIC_API_KEY=... POC_CWD=/path/to/project npm run poc

Security

• API keys live only in Claude Provider credentials.
• claudeModelConfig.sdkEnv contains secrets during execution — do not log full items in production.
• Use mcp_skills_only for production AI workflows that must not read or modify local code; use plan_only when MCP should also be disabled.
• customer_service / read_only allow Read/Grep/Glob against mounted Working Directories — only mount directories the agent is authorized to access.

License

MIT