# 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.

## Setup

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

```bash
npm run setup
cp .env.example .env
```

Fill in `.env`:

| Variable | What it is |
|---|---|
| `N8N_BASE_URL` | Your instance URL, like `https://you.app.n8n.cloud/`, trailing slash included |
| `N8N_API_KEY` | n8n Cloud, Settings, n8n API, Create an API key |
| `N8N_PROJECT_NAME` | The project to scope to. Blank means your default project |
| `N8N_WORKFLOW_PREFIX` | Defaults to `[CC] `, and the trailing space matters |

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](LICENSE).

More at [benattanasio.com/lab](https://benattanasio.com/lab).