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:

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

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

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):

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

After bridge pull (portable, committed to git):

{
  "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 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 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.

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.

Roadmap

• MCP server for Claude Code / Cursor
• 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.

About me

Ashkan Dorkian — AI-native frontend & automation engineer.