n8n Builder

An MCP server that lets Claude Code build, run, and manage workflows on your n8n Cloud instance. You describe what you want in a conversation, Claude writes the workflow JSON, pushes it to n8n, executes it, reads the result, and fixes it.

It can only ever touch workflows it created. That guarantee is the reason this exists rather than pointing an agent at the raw n8n API.

The scope guard

n8n's API gives you your whole instance. Handing that to an agent means a bad generation can rename, deactivate, or delete production workflows you've been running for months.

mcp-server/src/scope-guard.ts closes that off with a name prefix:

• Every workflow Claude creates is prefixed, [CC] by default.

• Modify, delete, execute, and activate are all rejected unless the workflow's name starts with that prefix.

• n8n_list_workflows only returns prefixed workflows, so Claude can't see the rest of your instance and can't decide to act on it.

• Credentials get the same prefix so they're identifiable.

Set N8N_PROJECT_NAME to scope to one n8n project as well. Leave it unset and every project is reachable, which is worth knowing before you skip it.

Folders in n8n Cloud aren't exposed through the API, so the prefix is the actual boundary. Move the [CC] workflows into a folder yourself if you want them grouped visually.

Related MCP server: n8n Workflow Builder

Setup

You need Node 20 or newer and an n8n Cloud account.

npm run setup
cp .env.example .env

Fill in .env:

Restart Claude Code and the tools register.

Your credentials only ever go in .env, which is gitignored. The MCP server loads it itself, so .mcp.json holds no environment block and is safe to commit. Putting keys in .mcp.json or in .claude/settings.json works too, and both of those are files people commit by habit, which is how keys end up in public repos.

If you'd rather have Claude walk you through it, run /setup and the skill in .claude/skills/setup/ handles the whole thing.

The tools

Workflows: n8n_list_workflows, n8n_get_workflow, n8n_create_workflow, n8n_update_workflow, n8n_delete_workflow, n8n_activate_workflow, n8n_deactivate_workflow

Executions: n8n_execute_workflow, n8n_get_execution, n8n_list_executions

Credentials: n8n_list_credentials, n8n_create_credential, n8n_delete_credential

File sync: n8n_import_from_file, n8n_export_to_file, n8n_sync_all_to_local, n8n_list_local_workflows

Building a workflow

The loop Claude runs:

1. Write the workflow as n8n JSON, which is nodes plus connections.

2. n8n_create_workflow pushes it.

3. n8n_execute_workflow runs it.

4. n8n_get_execution reads what came back.

5. n8n_update_workflow fixes whatever broke, and back to step 3.

6. n8n_export_to_file saves the final version into workflows/.

Every node needs name, type, typeVersion, position, and parameters. The types that come up most are n8n-nodes-base.httpRequest, n8n-nodes-base.webhook, n8n-nodes-base.set, n8n-nodes-base.if, n8n-nodes-base.code, and @n8n/n8n-nodes-langchain.agent.

For a workflow that needs an API key, n8n_create_credential takes the type (openAiApi, anthropicApi, httpHeaderAuth and so on) and the node references it through its credentials field.

Version control for workflows

workflows/ holds exported workflow JSON, and workflows/.id-map.json maps each filename to its n8n workflow id so a re-import updates the same workflow instead of creating a duplicate. The id map is gitignored since the ids are specific to your instance.

n8n_sync_all_to_local pulls every [CC] workflow down at once, which is how you get a diffable history of flows you built by conversation.

Three examples ship in workflows/ to import and pull apart: client-onboarding.json, lead-capture-enrich-notify.json, and weekly-client-report-digest.json. Their credential fields are empty, so you fill in your own.

Seeing the editor

n8n's visual editor opens inside VS Code. Ctrl+Shift+P, then Simple Browser: Show, then paste your n8n Cloud URL. Claude edits the JSON and you watch the graph change.

Layout

mcp-server/src/
  index.ts        MCP server entry point and tool registration
  n8n-client.ts   the n8n Cloud REST client
  scope-guard.ts  project resolution and prefix enforcement
  tools/          workflows, executions, credentials, sync
  types.ts
workflows/        exported workflow JSON
CLAUDE.md         how Claude should use the tools

Limitations

• n8n Cloud only. A self-hosted instance should work through the same public API, and it isn't tested.

• Folders can't be created or read, since the n8n API doesn't expose them.

• The prefix check is a name check. Renaming a workflow to start with [CC] brings it into scope, so don't do that to something you care about.

License

MIT. See LICENSE.

More at benattanasio.com/lab.