CommandBridge MCP

Project status

CommandBridge MCP is pre-1.0 software for controlled environments. The pinned raw GitHub installation commands below target v0.3.0; use them only after that tag is published. A checked-out repository can be installed directly.

Related MCP server: mcp-shell

Why CommandBridge?

CommandBridge is a cross-platform Model Context Protocol server for inspecting a host and running policy-bounded commands when SSH is unavailable or intentionally excluded from the workflow.

Highlights

• Cross-platform — Linux supports bash, sh, and optional pwsh; Windows supports PowerShell and cmd.exe.

• Policy-first execution — limits shells, command names, working directories, timeouts, output size, inherited environment variables, and concurrency.

• Audit trail — records attempted plus one final blocked, completed, or failed event without command output or unredacted secrets.

• Deployment assets — provides a Linux systemd installer and an x64 Windows service installer using WinSW and LocalService.

Quick start

Linux systemd

From a checked-out repository on a supported glibc-based Linux host with systemd:

git clone https://github.com/HsinPu/command-bridge-mcp-server.git
cd command-bridge-mcp-server
sudo bash scripts/linux-systemd/install.sh \
  --print-codex-setup \
  --codex-url "https://command-bridge.example.com/mcp"

The installer downloads a pinned Node.js runtime, builds and tests the source, creates the low-privilege command-bridge account, installs under /opt, enables the service, verifies /health, and prints a copy-ready Codex setup block.

Verify the service:

sudo systemctl status command-bridge-mcp-server --no-pager
curl -fsS http://127.0.0.1:8800/health

installer=$(mktemp)
curl -fsSL https://raw.githubusercontent.com/HsinPu/command-bridge-mcp-server/v0.3.0/scripts/linux-systemd/install.sh -o "$installer"
sudo bash "$installer" --print-codex-setup --codex-url "https://command-bridge.example.com/mcp"
rm -f "$installer"

See the Linux systemd guide for prerequisites, rollback, upgrades, audit access, and safe uninstall procedures.

Windows service

From an elevated PowerShell session in a checked-out repository:

git clone https://github.com/HsinPu/command-bridge-mcp-server.git
Set-Location command-bridge-mcp-server
.\scripts\windows\install.ps1 -PrintCodexSetup -CodexUrl "https://command-bridge.example.com/mcp"

The x64 installer verifies Node.js v24.18.0 and WinSW v2.12.0, runs the test suite, registers the CommandBridgeMCP Application Event Log source, and starts the service as NT AUTHORITY\LocalService.

See the Windows service guide for host requirements, Event Viewer queries, rollback, and uninstall commands.

Local development

git clone https://github.com/HsinPu/command-bridge-mcp-server.git
cd command-bridge-mcp-server
npm ci
cp .env.example .env
npm run build
npm start

The default transport is stdio. For Streamable HTTP, configure COMMAND_BRIDGE_TRANSPORT=http and a bearer token of at least 32 characters.

Connect Codex

For a remote Codex client, expose the loopback listener through a private HTTPS route such as Tailscale Serve, Cloudflare Tunnel, or an authenticated reverse proxy.

The recommended path is to use --print-codex-setup during installation and paste the marked block into a trusted Codex task. It keeps the bearer token out of config.toml and uses an environment variable instead.

For manual setup, store the token as COMMAND_BRIDGE_BEARER_TOKEN on the Codex client and add:

[mcp_servers.command_bridge]
enabled = true
url = "https://command-bridge.example.com/mcp"
bearer_token_env_var = "COMMAND_BRIDGE_BEARER_TOKEN"
startup_timeout_sec = 20.0
tool_timeout_sec = 60.0

Restart Codex, open /mcp, and confirm that command_bridge is connected.

How it works

flowchart LR
    client["Codex or MCP client"]
    transport{"Transport"}
    stdio["Local stdio"]
    http["Private Streamable HTTP"]
    auth["Bearer token and Host validation"]
    policy["Command policy and limits"]
    executor["Command executor"]
    audit["Redacted audit log"]
    host["Linux or Windows host"]

    client --> transport
    transport --> stdio --> policy
    transport --> http --> auth --> policy
    policy --> executor --> host
    executor --> audit

Each deployed host runs one MCP endpoint. A future gateway mode will coordinate multiple outbound-connected host agents.

MCP tools

Example command request:

{
  "command": "hostname",
  "shell": "bash",
  "cwd": "/var/lib/command-bridge-mcp-server/work",
  "timeoutMs": 15000
}

Command audit log

Every command_bridge_run_command call writes an attempted event before process start, followed by exactly one terminal blocked, completed, or failed event.

• If the first audit write fails, CommandBridge does not start the command.

• If a terminal audit write fails, CommandBridge withholds captured command output.

• Events include an audit ID, time, phase, redacted command, shell, working directory, execution mode, source, exit code, duration, timeout/truncation state, and error code.

• Events never include stdout, stderr, bearer tokens, environment values, or the unredacted command.

On Linux, events are written as compact JSON to the service journal. On Windows, they are written to the Application Event Log under CommandBridgeMCP. The host controls retention. This is operational evidence, not a signed, hash-chained, or tamper-evident compliance ledger.

Use the read-only tool to inspect recent records:

{ "limit": 50 }

Uninstall

The Linux standard uninstall removes the service, application, Audit reader, and its restricted sudoers rule while preserving configuration, work data, and the low-privilege account for a later reinstall.

uninstaller=$(mktemp)
curl -fsSL https://raw.githubusercontent.com/HsinPu/command-bridge-mcp-server/v0.3.0/scripts/linux-systemd/uninstall.sh -o "$uninstaller"
sudo bash "$uninstaller" --yes
rm -f "$uninstaller"

uninstaller=$(mktemp)
curl -fsSL https://raw.githubusercontent.com/HsinPu/command-bridge-mcp-server/v0.3.0/scripts/linux-systemd/uninstall.sh -o "$uninstaller"
sudo bash "$uninstaller" --purge --yes
rm -f "$uninstaller"

For Windows, run .\scripts\windows\uninstall.ps1 -Yes from an elevated PowerShell session. Add -Purge to delete %ProgramData%\CommandBridgeMCP; use -DryRun to preview actions.

Configuration and execution policy

Copy .env.example for manual development. The most important settings are:

allowlist mode rejects pipes, redirects, chaining, command substitution, and newlines. Use unrestricted only after reviewing the service account's operating-system permissions.

Supported hosts

Security model

Application policy is only one layer of defense.

• Keep allowlist mode unless unrestricted execution is explicitly required.

• Run CommandBridge under a dedicated non-administrator account.

• Use a unique bearer token per host and rotate it after suspected exposure.

• Keep HTTP private or behind authenticated TLS.

• Restrict allowed roots and inherited environment variables.

• Never place passwords, API keys, or private keys in command arguments.

• Do not add the Linux service account to sudo, docker, adm, or systemd-journal groups. The installer grants only one exact no-argument sudoers rule for its root-owned audit reader.

Read the complete security policy before deployment. Report vulnerabilities through a private GitHub Security Advisory, not a public issue.

Documentation

Development

npm ci
npm test

npm test compiles TypeScript and runs command-policy, audit lifecycle/redaction, MCP tool, Linux asset, uninstall asset, and Windows installer asset tests.

On Windows PowerShell, use npm.cmd when execution policy blocks npm.ps1.

src/                         Application source
docs/                        Deployment guides
packaging/linux/             Fixed Linux audit reader
packaging/systemd/           Linux systemd unit
packaging/windows/           WinSW service definition
scripts/linux-systemd/       Linux installer and uninstaller
scripts/windows/             Windows installer, uninstaller, and Event Log helpers

Roadmap

• Background jobs with polling and cancellation

• Central gateway with agent-initiated outbound connections

• OAuth 2.1 for remote MCP clients

• Signed host enrollment and per-host authorization scopes

• Signed prebuilt Linux release artifacts for offline installation

Contributing

Issues and pull requests are welcome.

1. Open an issue before a significant behavior or security-boundary change.

2. Create a focused branch.

3. Run npm test.

4. Open a pull request with the motivation, behavior change, and verification evidence.

Project links

• GitHub Actions

• Issues

• Releases and tags

• Security advisories