# n8n Flow Bridge

Git-based version control for n8n workflows with automatic credential
remapping — stop rewiring nodes every import.

## The problem

Exporting/importing n8n workflows breaks credential bindings because node
references point to internal instance-specific ids, not names. Every
environment switch (dev → prod, or teammate → teammate) means manually
reopening every credentialed node and rewiring it by hand. This tool fixes
that.

## What it does

- Pulls workflows from n8n into clean, diffable git files
- Auto-rewrites credential references to stable symbolic keys
  (`cred:<type>:<slug>`)
- Auto-remaps symbolic keys back to real local credential ids on push
- Detects and blocks on missing credential bindings before they break a
  workflow silently

## Quick start

No install step — works the same on Windows, macOS, and Linux:

```bash
export N8N_BASE_URL=http://localhost:5678
export N8N_API_KEY=...

npx n8n-flow-bridge-mcp pull --workflow 123
npx n8n-flow-bridge-mcp bind cred:slackApi:team-bot
npx n8n-flow-bridge-mcp push --workflow 123
```

Prefer a shorter command? `npm install -g n8n-flow-bridge-mcp` once, then use
`bridge` directly (`bridge pull --workflow 123`, etc.) instead of
`npx n8n-flow-bridge-mcp ...`.

### Developing on this repo instead of the published package

```bash
git clone https://github.com/dorkian/n8n-flow-bridge-mcp.git
cd n8n-flow-bridge-mcp
npm install
npm run build
npm link        # makes the local build available as `bridge`
```

Running separate dev and prod n8n instances from one checkout? Every command
accepts `-e, --env-dir <path>` (and `-d, --dir <path>` for `workflows/`
itself, rarely needed) to say which environment's `.env` and
`credentials.map.json` to use — point it at any two folders you like, e.g.:

```bash
bridge push --workflow 123 --env-dir ./environments/dev
bridge push --workflow 123 --env-dir ./environments/prod
```

`workflows/` stays a single shared, git-tracked folder; only `.env` and
`credentials.map.json` differ per environment. Register `bridge mcp
--env-dir <path>` twice (once per environment) to get the same separation
through MCP tools.

## Before / after

**Raw n8n export** (instance-specific, breaks on import elsewhere):

```json
{
  "name": "Post Release Alert",
  "type": "n8n-nodes-base.slack",
  "credentials": {
    "slackApi": { "id": "17", "name": "Team Bot" }
  }
}
```

**After `bridge pull`** (portable, committed to git):

```json
{
  "name": "Post Release Alert",
  "type": "n8n-nodes-base.slack",
  "credentials": {
    "slackApi": { "id": "cred:slackApi:team-bot", "name": "Team Bot" }
  }
}
```

`bridge push` remaps `cred:slackApi:team-bot` back to whatever the real
local credential id is on the target machine — see
[docs/credential-remap.md](docs/credential-remap.md) for the full
walkthrough.

## CLI commands

| Command | What it does |
|---|---|
| `bridge pull --workflow <id>` / `--all` | Fetch, sanitize, and save workflow(s) to `workflows/` |
| `bridge push --workflow <id\|file\|name>` / `--all` | Remap credentials and push workflow(s) to n8n |
| `bridge bind <cred-key>` | Bind a symbolic credential key to a local credential id |
| `bridge bind --auto` | Auto-bind all unbound keys by exact type + name match |
| `bridge status` | Show credential drift and remote sync status |
| `bridge mcp` | Run the MCP server (stdio) for Claude Code / Cursor |

All of the above accept `-e, --env-dir <path>` (which `.env` +
`credentials.map.json` to use) and `-d, --dir <path>` (where `workflows/`
lives, defaults to cwd, rarely needs overriding).

## Configuration

Set `N8N_BASE_URL` and `N8N_API_KEY` (env vars or a `.env` file, optionally
loaded from `--env-dir`).

## Want AI to build the workflow itself, not just version it?

This tool has no opinion about which n8n nodes solve your problem — pair it
with [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) for that (node
catalog, validation, natural-language workflow creation/editing on dev),
and use `bridge` to snapshot the result into git and promote it to prod.
See [docs/pairing-with-n8n-mcp.md](docs/pairing-with-n8n-mcp.md).

## Architecture

`bridge pull` fetches a workflow from n8n, strips instance-specific
metadata, and rewrites each node's credential id to a portable symbolic key
(`sanitize.ts`) before writing it to `workflows/` in a deterministically
ordered, diff-friendly format (`diffFormat.ts`). Each machine keeps a
git-ignored `credentials.map.json` binding those symbolic keys to its own
real credential ids (`credentialMap.ts`). `bridge push` substitutes the
real ids back in (`remap.ts`) — aborting first if any key is unbound — then
calls the n8n API. The CLI (`src/cli/*`) and the MCP server
(`src/mcp/server.ts`) both call the same core modules, so both surfaces stay
in sync. Full details in [docs/architecture.md](docs/architecture.md).

## Roadmap

- [x] MCP server for Claude Code / Cursor
- [x] Multi-environment support from one checkout (`--env-dir`)
- [ ] Web UI for credential binding
- [ ] Multi-instance orchestration (sync dev → staging → prod in one command)

See [docs/roadmap.md](docs/roadmap.md).

## About me

Ashkan Dorkian — AI-native frontend & automation engineer.