brokre

MCP launcher for brokre — a local credential broker for AI agents. Use it with Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Hermes Agent, ChatClaw, and other MCP-capable clients to run ssh / mysql / psql and more — passwords never enter AI context, environment variables, or ps output. Agents list credential aliases and execute saved connections via MCP without exposing passwords to the AI.

Developed by Techinone (成都同创合一科技有限公司).

Current version: 0.2.8 · npm

What's New in 0.2.8

npm install — auto MCP setup + auto binary upgrade

npm install -g brokre
# or use without global install:
npx -y brokre@latest

| Feature | Behavior | |---------|----------| | Auto MCP registration | postinstall → brokre-setup-mcp. Detects installed IDEs only; merges npx -y brokre@latest into global MCP config. Idempotent — no duplicate entries, no writes for missing software. | | Auto binary upgrade | Each MCP start compares npm version vs ~/.brokre/bin/brokre / PATH; downloads matching release when needed. | | Manual controls | brokre mcp setup · npx brokre-setup-mcp · --dry-run · --force · skip: BROKRE_MCP_SKIP_SETUP=1 |

IDEs with auto-setup (global config paths):

| IDE | Config file | |-----|-------------| | Cursor | ~/.cursor/mcp.json | | VS Code | …/Code/User/mcp.json | | VS Code Insiders | …/Code - Insiders/User/mcp.json | | Claude Code | ~/.claude.json | | Claude Desktop | …/Claude/claude_desktop_config.json | | Trae | …/Trae/User/mcp.json | | Kimi Code | ~/.kimi-code/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | OpenClaw | ~/.openclaw/openclaw.json (mcp.servers) |

Bastion broker — cluster management

Operate many inner hosts through one jump box — passwords stay on the bastion, not in AI context.

| Advantage | What it means in practice | |-----------|----------------------------| | Single control plane | Register bastion alias b150, sync inner aliases, drive cluster via brokre_list | | Smart routing | b150::db, multi-hop b1::b2::inner — separator ::; access=via_b150 when LAN is down | | Secrets on bastion | Routed exec uses remote ~/.brokre/bin/brokre; laptop holds metadata + gate only | | Human gate | Unlock via TTY, /bastion-auth, or MCP URL elicitation; survives manage UI idle expiry | | Cluster-safe list | Probes, hides unreachable locals, loop detection, audit route/bastion | | Privileged over routes | brokre_exec_elevated, sudo/sudo -i through bastions with session reuse |

Gate policy (default vs strict) — inactive until brokre bastion set-key. Default: unlock only for bastion outbound (:: routes, registered bastion SSH, bastion list discovery). Strict: every exec/list requires unlock. CLI: brokre bastion strict on|off|status · MCP: brokre_bastion_policy. Config: ~/.brokre/bastion/policy.json. See main README.

Typical MCP flow:

{ "binary": "ssh", "args": ["b150::db", "uname", "-a"] }

CLI setup:

brokre bastion enable b150
brokre bastion sync b150 --json
brokre bastion unlock
brokre list --json

See brokre_list — cross-network smart list below.

Prerequisites

• Node.js 18+ (for npx)
• No Rust required — downloads or upgrades a prebuilt brokre from GitHub Releases into ~/.brokre/bin/ when the local binary is missing or older than the npm package version.
• Elevated session pool (persistent sudo/su shells): Unix only (macOS / Linux).

Optional — install the CLI yourself (recommended for production):

curl -fsSL https://raw.githubusercontent.com/Furowu/brokre/main/install.sh | bash

Re-run the same command to upgrade; the script skips download when already up to date.

Supported clients

Any tool with stdio MCP support can use brokre — configure npx -y brokre@latest (or brokre mcp after CLI install) as the MCP server command. Tested and documented below for Cursor and Claude Code; the same pattern applies to Kimi Code, Trae, OpenClaw, Hermes Agent, ChatClaw, and similar agents.

Cursor

One-click install: Install brokre in Cursor

Or add to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "brokre": {
      "command": "npx",
      "args": ["-y", "brokre@latest"]
    }
  }
}

Or use the native binary directly (no Node, after CLI install):

{
  "mcpServers": {
    "brokre": {
      "command": "brokre",
      "args": ["mcp"]
    }
  }
}

Claude Code

Project scope (.mcp.json at repo root):

{
  "mcpServers": {
    "brokre": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "brokre@latest"]
    }
  }
}

CLI:

claude mcp add --scope project brokre -- npx -y brokre@latest

Auto-update

Recommended: npx -y brokre@latest so the npm launcher stays current (package version 0.2.8).

On each MCP start, this package compares the npm package version with any local brokre binary (on PATH or in ~/.brokre/bin/). If the binary is missing or older, it downloads the matching release from GitHub into ~/.brokre/bin/ and uses that — even when an older brokre is already on PATH.

Auto MCP registration (npm i brokre, 0.2.8+)

On npm install brokre (local or global), postinstall runs brokre-setup-mcp, which detects installed IDEs (app bundle, CLI, or real usage artifacts — not empty directories) and merges a global brokre MCP entry (npx -y brokre@latest) into each client's config file. Does not create config files for software that is not installed. Existing non-brokre servers are preserved; duplicate brokre aliases under other names are not added.

| IDE | Global config path | |-----|-------------------| | Cursor | ~/.cursor/mcp.json | | VS Code | ~/Library/Application Support/Code/User/mcp.json (macOS) | | VS Code Insiders | …/Code - Insiders/User/mcp.json | | Claude Code | ~/.claude.json (mcpServers) | | Claude Desktop | …/Claude/claude_desktop_config.json | | Trae | …/Trae/User/mcp.json | | Kimi Code | ~/.kimi-code/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | OpenClaw | ~/.openclaw/openclaw.json (mcp.servers) |

Manual re-run: brokre mcp setup or npx brokre-setup-mcp (add --dry-run to preview, --force to overwrite). Skip on install: BROKRE_MCP_SKIP_SETUP=1.

CLI on PATH: On first download, brokre-mcp adds ~/.brokre/bin to your shell profile (~/.zshrc, etc.) and tries to symlink /usr/local/bin/brokre when writable. Open a new terminal (or source ~/.zshrc) so brokre manage works.

Empty vault: Each MCP connect while the vault has no credentials starts brokre manage in the background and opens http://127.0.0.1:56777/?t=… (or the next free port) in your default browser. Session tokens are never returned to the AI.

Manual CLI install (install.sh) does the same version check: re-run the script to upgrade when a newer release is available.

First connection

When the vault is empty, brokre mcp automatically opens brokre manage in your browser (e.g. http://127.0.0.1:56777/?t=…) so you can add accounts. Session tokens are never returned to the AI — only your browser receives them.

Disable auto-open: BROKRE_MCP_NO_AUTO_OPEN=1

MCP tools

| Tool | Purpose | |------|---------| | brokre_list | Saved aliases (metadata only); auto smart-list when bastions registered — probe, merge bastion::inner routes, hide unreachable | | brokre_exec | Run a saved connection (binary + args); ssh + shell_command for remote scripts; ssh + sudo/su auto-reuses elevated session | | brokre_exec_elevated | Remote privileged command (alias, command, mode); default session=reuse | | brokre_setup | Open manage UI in browser for the human | | brokre_audit_list | Query audit history (metadata only — args redacted) | | brokre_audit_verify | Verify tamper-evident audit log chain | | brokre_bastion_policy | Read/set gate mode: default (bastion outbound only) or strict (all exec/list); returns key_set, unlocked |

Not exposed: reveal, password export, or manage session tokens.

CLI basics

The npm package launches MCP, but the underlying tool is the brokre CLI (~/.brokre/bin/brokre or PATH). Humans and agents debugging in a terminal use the same vault.

Always prefix brokre — bare ssh prod / mysql prod does not inject saved passwords.

brokre list --json                    # list aliases (metadata only)
brokre ssh prod uname -a              # SSH one-shot (split argv after alias)
brokre mysql prod-db -e "SHOW TABLES"
brokre ssh prod sh -c 'echo hi > /tmp/f'   # remote script ( -c script is one arg )
brokre manage --open                  # add credentials in browser
brokre ssh [email protected]              # first-time save (TTY; type password when prompted)

Run brokre --help for pass-through syntax and subcommands (list, manage, mcp, bastion, …).

MCP ↔ CLI mapping

| Task | MCP | CLI | |------|-----|-----| | List aliases | brokre_list | brokre list --json | | SSH command | brokre_exec binary=ssh, args=["prod","uname","-a"] | brokre ssh prod uname -a | | Other CLI | brokre_exec binary=mysql, args=[…] | brokre mysql <alias> … | | Remote script | shell_command="…" | brokre ssh <alias> sh -c '…' | | Privileged | brokre_exec_elevated | brokre ssh <alias> sudo … | | Setup | brokre_setup | brokre manage --open |

AI antipatterns: ssh prod cmd (missing brokre); MCP args=["prod","cmd arg"] (use argv tokens or shell_command).

brokre_list — cross-network smart list

When bastions are registered on the laptop, brokre_list automatically (no extra params):

1. TCP-probes local and bastion-discovered aliases
2. Merges routed entries like b150::db (route: ["b150"], access: "via_b150")
3. Hides unreachable aliases (e.g. local LAN db when off-network)

Use all: true to include unreachable entries. Prefer addr with availability: "available"; for cross-network inner hosts use bastion::inner in brokre_exec args.

Example response (cross-network via VPN to bastion b150):

{
  "items": [
    {
      "profile": "ssh",
      "name": "db",
      "addr": "b150::db",
      "route": ["b150"],
      "kind": "inner",
      "access": "via_b150",
      "host_alias": "10.0.0.20",
      "availability": "available",
      "status": {
        "reachable": true,
        "probe_ms": 3,
        "source": "b150",
        "checked_at": "2026-06-21T12:00:00Z"
      }
    }
  ],
  "bastion_gate": {
    "required": true,
    "unlocked_during_call": true,
    "idle_expires_at": "2026-06-21T12:10:00Z"
  }
}

Execute routed alias:

{ "binary": "ssh", "args": ["b150::db", "uname", "-a"] }

When both direct and routed paths work, both appear — access: "direct" vs access: "via_b150".

Bastion gate policy (default vs strict)

| Mode | Unlock required when key is set | |------|----------------------------------| | default (strict_mode: false) | Bastion outbound only: b150::db routes, SSH to registered bastion aliases, brokre_list with bastion discovery. Local brokre_exec to LAN aliases — no unlock. | | strict (strict_mode: true) | Every brokre_exec and brokre_list. |

brokre bastion set-key           # gate inactive until this
brokre bastion strict status
brokre bastion strict on         # strict
brokre bastion strict off        # default
brokre bastion unlock

{ "strict_mode": true }

MCP brokre_bastion_policy (omit strict_mode to read). Unlock TTL defaults: 30 min idle / 8 h max — env BROKRE_BASTION_IDLE_SECS, BROKRE_BASTION_MAX_SECS. List/exec include bastion_gate in responses.

Elevated sessions (brokre_exec_elevated)

Runs a command on a saved SSH host with sudo, sudo -i environment (sudo_login), or su. By default the MCP server reuses a background elevated shell (same alias + mode + user) so sudo is not re-prompted every call.

{
  "alias": "prod",
  "command": "systemctl restart nginx",
  "mode": "sudo_login",
  "session": "reuse"
}

| Field | Values | |-------|--------| | mode | sudo, sudo_login (aliases: sudo-i), su | | session | reuse (default), new, close (use command: "") | | user | Target user for su; default root |

Response (session pool enabled): exit_code, stdout, stderr, session_reused, session_idle_expires_at. The expiry field is a rolling idle-window hint, not a fixed deadline. With BROKRE_MCP_SESSION=0, only the first three fields are returned (one-shot subprocess).

brokre_exec shortcut: binary=ssh, args=["prod","sudo","systemctl","status","nginx"] uses the same pool (always reuse; cannot pass session=new|close).

Writing remote scripts (shell_command)

For scripts or file writes with complex quoting, use shell_command (ssh only). Pass only the alias in args; brokre runs sh -c <shell_command> on the remote host.

{
  "binary": "ssh",
  "args": ["prod"],
  "shell_command": "cat > /tmp/deploy.sh <<'EOF'\n#!/bin/sh\necho ok\nEOF"
}

Do not: put sh -c '...' in args, split printf/redirects across argv tokens, or rely on line-by-line echo >> workarounds. For privileged paths use brokre_exec_elevated.command. Bastion routes: args=["b150::db"] with the same shell_command field.

Limits: idle teardown 10 min, max lifetime 30 min, per-command timeout 120 s (configurable via env below). No interactive sudo -i without a command, no vim/top. Sudo password must match vault password.

Environment

| Variable | Description | |----------|-------------| | BROKRE_MCP_SKIP_SETUP | Set to 1 to skip auto MCP registration on npm install | | BROKRE_BIN | Pin a specific brokre binary (skips version check and auto-download) | | BROKRE_VERSION | Release version to download (default: npm package version) | | BROKRE_SKIP_AUTO_INSTALL | Set to 1 to use PATH only, no GitHub download | | BROKRE_MCP_NO_AUTO_OPEN | Set to 1 to skip browser on empty vault | | BROKRE_MCP_SESSION | Set to 0 to disable elevated session pool (default: enabled on Unix) | | BROKRE_MCP_SESSION_IDLE_SECS | Idle session teardown (default: 600) | | BROKRE_MCP_SESSION_MAX_SECS | Max session lifetime (default: 1800) | | BROKRE_MCP_SESSION_CMD_TIMEOUT | Per remote command timeout in seconds (default: 120) | | BROKRE_BASTION_NO_AUTO_OPEN | Set to 1 to skip browser on bastion gate unlock (non-TTY) | | BROKRE_BASTION_IDLE_SECS | Bastion unlock idle timeout in seconds (default: 1800) | | BROKRE_BASTION_MAX_SECS | Bastion unlock max session lifetime in seconds (default: 28800) |

License

MIT · Techinone