Bridge Commander

A self-hosted Model Context Protocol server that gives an AI assistant (Claude Desktop, Claude Code, ChatGPT connectors, any MCP client) hands on your machines:

• Files: read (text, images, Word, Excel, PDF, URLs, line ranges, tail), write, append, exact-text edit_block, move, mkdir, info

• Search: find files by name/glob, grep contents with regex and context; background searches with paging

• History: recent tool calls and usage statistics from the audit log

• Terminal sessions: long-running and interactive commands with incremental output and stdin

• Processes: list and kill system processes

• Remote nodes: one server fans out to other machines over SSH (or any command), each with its own rules

• Two transports: stdio for local clients, Streamable HTTP with a token for remote clients

No dependencies beyond the Python standard library. Use a maintained Python 3.12 or newer; the source also has compatibility checks on 3.9. The client ships as one .pyz file.

Русская версия

Quick start

git clone https://github.com/PaPasha215/bridge-commander-core && cd bridge-commander-core
python3 scripts/build_pyz.py                 # -> dist/bridge-commander.pyz
python3 dist/bridge-commander.pyz init       # writes ~/.config/bridge-commander/config.json

Or install as a command: pipx install . (then use bridge-commander instead of python3 …pyz).

Claude Code

claude mcp add bridge-commander -- python3 /absolute/path/bridge-commander.pyz serve

Claude Desktop

Add to claude_desktop_config.json (see examples/claude_desktop_config.json):

{"mcpServers": {"bridge-commander": {"command": "python3", "args": ["/absolute/path/bridge-commander.pyz", "serve"]}}}

Over SSH (a server somewhere else, no open ports)

claude mcp add my-server -- ssh my-server python3 bridge-commander.pyz serve

Remote HTTP clients (ChatGPT, claude.ai connectors, anything with a URL)

python3 bridge-commander.pyz token --write ~/.config/bridge-commander/token
python3 bridge-commander.pyz serve --transport http          # http://127.0.0.1:8765/mcp

Then publish the loopback port through a tunnel you trust. See docs/REMOTE.md.

Hosted cloud (no server of your own)

The free beta uses Bridge Commander Cloud. On a new macOS/Linux profile:

curl -fL --output bridge-commander.pyz https://bridgecommander.dev/download/bridge-commander.pyz &&
python3 -I bridge-commander.pyz init --directory ~/BridgeFiles &&
python3 -I bridge-commander.pyz remote --cloud https://bridgecommander.dev

Verify the downloaded 1.3.0 artifact against SHA256SUMS. Keep the MIT LICENSE with redistributed copies. Setup stops if a download or initialization fails. Inspect an existing configuration before changing it; do not add --force to this sequence.

The machine connects out over HTTPS, you confirm a code in the browser, and the chat connects to the cloud's MCP URL with OAuth. The device still enforces its own config file. remote --logout forgets the device credentials; revoking the device in the dashboard cuts access at once.

Backup route: remote --fallback https://edge.<cloud address> (repeatable; saved with the credentials). When the main address stops answering (a VPN drops, a network blocks the IP), the client switches to the first backup whose /health answers, and every 5 minutes checks whether the main address is back. A backup must be on the cloud's own domain, so the device token never goes to another host.

Related MCP server: MCP Local File Reader

Configuration

~/.config/bridge-commander/config.json (or --config FILE, or $BRIDGE_COMMANDER_CONFIG). Every key is optional.

The table lists underlying defaults for a manually supplied partial configuration. init instead writes an explicit private configuration for ~/BridgeFiles with read-only enabled. --allow-writes also permits commands with your OS user's rights. Run one remote client per OS profile: --config selects file rules, while saved device credentials are shared by that profile.

bridge-commander check validates the file and pings every node.

Remote nodes

A hub runs the MCP server. Each node runs bridge-commander worker, reached by any command that connects stdin/stdout — normally ssh. Every tool gains a node argument (local or a node name).

{
  "nodes": {
    "build-box": {
      "command": ["ssh", "-T", "-o", "BatchMode=yes", "build-box", "python3 ~/bin/bridge-commander.pyz worker"],
      "description": "Linux build server"
    }
  }
}

• The worker applies its own config on its machine (allowed directories, read-only, blocked commands). The hub cannot widen them.

• The SSH connection is kept open, so terminal sessions on a node survive between calls. If the link drops it is re-opened on the next call; sessions that lived in the old worker are gone.

• Copy the worker with scp dist/bridge-commander.pyz build-box:bin/. Nothing else has to be installed.

Tools

Security

Read docs/SECURITY.md before exposing it to a network. In short: this is remote shell access by design. allowedDirectories confines the file tools, but commands started with start_process run with your user's full rights. Use a dedicated user, readOnly, and a secret token; keep the HTTP listener on loopback behind an authenticated tunnel.

Development

python3 -m unittest discover -s tests -v    # stdlib only
python tests/sdk_compat.py                  # needs `pip install mcp`; checks the official SDK client

Candidate 1.3.0: 80 tests pass on macOS with Python 3.9 and 3.12. On Linux with Python 3.12, 79 tests pass and one PDF test is skipped because the optional converter is absent. These are isolated fixture checks. A real Linux CLI path through public HTTPS, delivered login email, device approval, OAuth, scoped read/search, authorized text changes and access revocation has also been checked. Fresh ChatGPT/mobile host acceptance and public capacity remain separate checks. The hosted route is Bridge Commander Cloud over OAuth.

PDF text: pdftotext (poppler) when present, otherwise the PDFKit built into macOS. On Windows install poppler (a Windows build of poppler with its bin folder on PATH, e.g. scoop install poppler) to read PDF; everything else needs nothing beyond Python.

License

MIT — see LICENSE.

CI: ci/github-actions-test.yml runs the tests on Linux and macOS. To enable it, copy it to .github/workflows/test.yml (pushing workflow files needs a token with the workflow scope).

First free public beta — client 1.3.0

The initial macOS/Linux path is a foreground Python .pyz in a terminal, a fresh private configuration and ~/BridgeFiles read-only. Use a maintained, patched Python; public installer acceptance is separate from compatibility tests. Do not run remote after a failed init, overwrite an existing configuration, or run two clients with the same credentials. Folder rules bound file tools; system/process/history queries have a broader read scope.

The client runs in the foreground terminal. Closing it stops new requests. An Apple Developer account is not needed to use this Python client or the ChatGPT plugin.

Remote sign-in now requires an explicit sharing configuration. Start with bridge-commander init --directory /path/to/shared-folder; the generated configuration is read-only and private. --allow-writes also enables commands with the OS user's permissions. The remote protocol requires the matching Cloud receipt API and finite delivery deadlines. Private metadata receipts prevent automatic replay across reconnect/restart; full outputs are kept only in bounded memory. Windows remote journal ACL acceptance is still pending.

Support: support@bridgecommander.dev. Include the client version, OS, error time and call identifier when available; omit passwords, tokens and private file contents.