n8n-axi

September 15, 2026 · View on GitHub

AXI-compliant CLI for n8n over the official n8n MCP server — agent-ergonomic workflow operations. Built against AXI spec axi/1.0-2026-07, Node.js 20+, TypeScript.

Search, inspect, run, test, publish, and archive workflows; triage executions; manage projects, folders, tags, data tables, and credentials; and author workflows through the validate-then-create loop — all with token-efficient TOON output, env-only auth, and confirmation gates on every mutation.

n8n-axi talks to your instance's instance-level MCP server (Streamable HTTP). It requires no n8n API key REST endpoint; the MCP server URL and a personal access token are all it needs.

Install

npm install -g n8n-axi     # or: npx -y n8n-axi <command>

Install the packaged agent skill:

npx -y skills@latest add brycehamrick/n8n-axi --skill n8n-axi -g

From a checkout:

npm install
npm run build
npm link
n8n-axi --help

Without linking, run node bin/n8n-axi.js.

Authentication

In n8n: Settings > Instance-level MCP > Connect a client > API key — copy the Server URL (ends in /mcp-server/http) and the token:

export N8N_MCP_URL="https://n8n.example.com/mcp-server/http"
export N8N_MCP_TOKEN="<personal access token>"

Security properties:

Credentials are read from the environment only — never from command arguments, config files, or prompts.
The token is sent as a bearer header and is scrubbed from every error message before output.
N8N_MCP_URL must use HTTPS; plain HTTP is allowed only for loopback hosts (local self-hosted n8n).
Optional N8N_MCP_TIMEOUT_MS (1000–600000, default 30000) bounds each MCP call.

Help and discovery (--help, --version) work without authentication.

Commands

# Live dashboard: workflow counts, 24h execution rollup, recent updates
n8n-axi

# Workflows
n8n-axi workflows list --query invoice --active --limit 50
n8n-axi workflows view <id>              # nodes, triggers, publish state
n8n-axi workflows run <id> --confirm --wait
n8n-axi workflows run <id> --mode production --trigger 'Webhook' \
  --input-type webhook --input '{"body":{"a":1}}' --confirm
n8n-axi workflows pin <id>               # which nodes need pin data, with schemas
n8n-axi workflows test <id> --pin @pin.json --confirm
n8n-axi workflows publish <id> --confirm
n8n-axi workflows unpublish <id> --confirm
n8n-axi workflows archive <id> --confirm        # idempotent
n8n-axi workflows history <id>
n8n-axi workflows version <id> <version-id>
n8n-axi workflows restore <id> --version <version-id> --confirm

# Executions
n8n-axi executions list --status error --after 2026-09-13T00:00:00Z
n8n-axi executions view <workflow-id> <execution-id> --data --nodes 'HTTP Request'

# Organization
n8n-axi projects list --query Marketing   # exact names resolve to IDs elsewhere
n8n-axi folders list --project Marketing
n8n-axi tags

# Data tables
n8n-axi tables list --project Marketing
n8n-axi tables create --project Marketing --name Leads \
  --column name:string --column score:number --confirm
n8n-axi tables rows Leads --project Marketing --rows '[{"name":"Ada","score":9}]' --confirm
n8n-axi tables column add Leads --name stage --type string --confirm
n8n-axi tables column rename Leads --column stage --name pipeline_stage --confirm
n8n-axi tables column delete Leads --column stage --confirm
n8n-axi tables rename Leads --name Leads2026 --confirm

# Credentials (names and IDs only - secrets are never returned)
n8n-axi credentials --type slackApi

# Authoring workflows (validate-then-create loop)
n8n-axi build best-practices scheduling    # bare: list all techniques
n8n-axi build nodes gmail                  # node IDs + discriminators
n8n-axi build node-types n8n-nodes-base.gmail --resource message --operation send
n8n-axi build resources --node-type n8n-nodes-base.slack --node-version 4.7 \
  --method channelSearch --method-type listSearch \
  --credential-type slackApi --credential <credential-id>
n8n-axi build sdk-reference                # patterns; --section guidelines|design|all
n8n-axi build validate --file workflow.ts
n8n-axi build create --file workflow.ts                     # dry-run
n8n-axi build create --file workflow.ts --project Marketing --confirm
n8n-axi build update <id> --ops @ops.json --confirm         # atomic op batch

# Ambient context (opt-in)
n8n-axi setup status
n8n-axi setup hooks --confirm              # session-start home view in Claude Code / Codex / OpenCode
n8n-axi setup uninstall --confirm

Every command supports --help (groups, subcommands, and nested groups alike). Data commands accept --json.

Safety gate

Every network mutation requires --confirm, checked before any network request:

workflows run, workflows test, workflows publish, workflows unpublish, workflows archive, workflows restore
tables create, tables rename, tables rows, tables column add|rename|delete
setup hooks, setup uninstall

build create and build update are dry-run by default: create validates the SDK code server-side and reports the target project and node count, then creates only when --confirm is present; update parses and describes the operation batch before applying it with --confirm. The gate authorizes one invocation only — there are no prompts and no remembered consent.

Reads never require confirmation. workflows archive is idempotent: archiving an already-archived workflow reports already archived (no-op) without another call.

Output and exit codes

Compact TOON is the default on stdout:

$ n8n-axi workflows list --limit 3
count: 11
workflows[3]{id,name,active,updated_at}:
  wfA9x2Qr...,Invoice sync,true,"2026-09-13T10:14:03.000Z"
  ...
truncated: workflows: showing 3 of 11 on this page (raise --limit up to 200)
help[2]: Run `n8n-axi workflows view <id>` for nodes, triggers, and publish state,...

Large text fields truncate with a size hint and a --full escape hatch; empty results are explicit (result: 0 workflows match the current filters); every output ends with contextual help[] next steps.

Errors are structured on stdout with a code and corrective suggestions. Secrets never appear in output.

Code	Meaning
`0`	Success (including informational help and definitive empty states)
`2`	Usage error: unknown command/flag, invalid value, missing argument, missing `--confirm`, unset environment
`1`	Runtime error: network, timeout, auth rejected, n8n API failure, unsupported tool

Unknown flags and commands fail loud with the valid options listed. There are no interactive prompts.

n8n version compatibility

The n8n MCP server renamed several tools in n8n 2.34.0 (get_execution → get_workflow_execution, search_executions → search_workflow_executions, list_tags → list_workflow_tags, prepare_test_pin_data → prepare_workflow_pin_data). n8n-axi resolves names through tools/list at call time, so both pre- and post-2.34 instances work without flags. When an instance lacks a tool entirely, the CLI reports UNSUPPORTED_TOOL with the closest tools that instance does expose.

Development

npm test          # vitest; fully mocked transport, no credentials needed
npm run typecheck

The test suite covers the MCP client (SSE parsing, alias resolution, error mapping, token scrubbing) and the CLI end to end (exit codes, empty states, truncation hints, confirmation gates asserted with call-level transport mocks).

UNRESOLVED / intentionally not implemented

get_workflow_versions_diff (n8n 2.36+): version comparison is available via workflows history + workflows version; a dedicated diff command may follow once the tool is widespread.
Agents (n8n 2.34+, preview): the agents MCP surface is in preview and not exposed.
OAuth login/token refresh: the MCP server's OAuth flow requires an interactive browser round trip; this CLI consumes a pre-issued API key from the environment and does not implement an unsafe partial flow.
Raw n8n REST API access: out of scope by design — this CLI wraps the official MCP server only.
MCP resources/prompts: only tools/* is used.
n8n-axi update is provided by axi-sdk-js as a built-in self-update command.

Official documentation used

Connect to n8n MCP server
MCP server tools reference
Live tool schemas from a connected instance (tools/list) covering both pre- and post-2.34 name sets.

Adding n8n-axi to the AXI catalog

The catalog entry prepared for kunchenguid/axi lives in docs/axi-catalog-entry.md along with the contributor workflow notes. PRs to the catalog must go through no-mistakes per that repo's CONTRIBUTING.md.

License

MIT