How to build n8n custom nodes with Claude Code

Why build a custom node at all

You build an n8n node when the integration you need doesn't exist, or exists as a community node that lags the API you actually have to call. The alternative — a wall of HTTP Request nodes with hand-set headers copy-pasted across every workflow — works until the API changes and you're editing forty workflows instead of one package. A node centralizes the auth, the endpoints, and the quirks in one place your whole team imports. The mechanics of that node are covered in the TypeScript boilerplate lab; this page is about building one fast with Claude Code without shipping something you don't understand.

The Claude Code loop for node development

Node development is unusually well-suited to an AI coding loop because the shape is so fixed — a description object and an execute path, both following patterns Claude has seen thousands of times — and because the feedback is concrete: it either appears correctly in the n8n canvas and returns data, or it doesn't. That tight, checkable loop is what makes the difference between AI that helps and AI that hallucinates. The loop is: give Claude the context, have it write the node, build and load it, feed the real result back, iterate.

1. Set up context files

Claude Code writes a better node when it can see the target. Drop the API's docs (or an OpenAPI spec) into the repo, and add a short project file — a CLAUDE.md — stating the n8n version you're targeting, whether you want a declarative or programmatic node, and the house rules (which lint config, naming conventions). Without this, Claude will pick a plausible-but-wrong n8n API surface, because n8n's node interfaces have shifted across versions and its training has seen all of them. Pin it to the one you're on.

2. Write the node spec, not just "make a node"

The quality of the node tracks the quality of the spec you hand Claude. "Build an n8n node for the Acme API" gets you a generic guess. "Build a declarative n8n node wrapping Acme's v2 API: a Contact resource with get / create / list operations, header-auth credential using a bearer token plus an X-Acme-Version header, base URL https://api.acme.com/v2, and list should paginate on the cursor field" gets you something close to shippable. You're not writing the code, but you are writing the interface — that's the part that needs a human who knows the API.

3. Generate description and execute, then read them

Let Claude produce the description object and, for a programmatic node, the execute() method. Then read what it wrote before you run it — specifically the auth wiring and the error handling, which are where a confident-looking node is most often subtly wrong. A common miss when wrapping GoHighLevel: Claude will set the bearer token but omit the mandatory Version header, producing a node that 401s exactly like the token-scope 401 — right-looking code, wrong result. You catch that by reading, not by hoping.

Testing what it writes

Treat AI-generated node code as a competent draft from someone who's never called this specific API. Build it, link it into a local n8n, and click through every operation against the real endpoint — the loop from the boilerplate lab. Where there's real logic in execute(), have Claude write unit tests too, but read those tests: an AI will happily write a test that asserts the buggy behavior it just produced. The test is only worth something if a human confirmed the expected value independently. Feed failures back to Claude with the actual error and the actual response body — concrete feedback fixes nodes fast; "it doesn't work" sends it in circles.

Publishing

Claude can scaffold the whole publish setup — the package.json n8n block, the keyword, the build script, a release workflow. That's genuine time saved on boilerplate. What it can't do is vouch that the package is clean and current on npm; I keep this page's claims to the process, not to the live published state of any particular package. Run n8n's community-package linter yourself before publishing and don't let the model assert something is verified or live that you haven't confirmed.

Where AI helps and where it doesn't

It helps most on the mechanical and pattern-heavy parts: the description object, credential wiring, pagination boilerplate, the publish scaffold, and turning a clear spec into a first draft in minutes instead of an hour. It helps least — and hurts if you trust it — on anything requiring judgment about the specific API: which auth flow the service actually uses, how it really paginates, its undocumented rate limits and error shapes, and whether the node's ergonomics make sense for the person who'll use it in a workflow. The winning division of labor is you own the interface and the API knowledge, Claude owns the typing-it-out. That's exactly the Harness Engineering pattern — configuring Claude Code against a real stack so it accelerates the mechanical work while a human keeps the judgment — and it's the same discipline behind building your own MCP server.

See how I build harnesses and nodes for clients →