CommandBridge

Cross-platform Model Context Protocol server for policy-controlled command execution on Linux and Windows.

CommandBridge MCP is designed for machines that cannot or should not be managed through SSH. Install the server on the target host, connect through local stdio or a private Streamable HTTP endpoint, and let an MCP client run bounded commands.

Status: early 0.2.0 implementation. Use on test machines before production.

Design goals

• Linux and Windows support from one TypeScript codebase.
• No SSH dependency.
• Safe allowlist mode by default.
• Explicit opt-in for unrestricted shell execution.
• Bounded time, output size, working directories, environment variables, and parallelism.
• Structured MCP results for both host information and command execution.

Architecture

flowchart LR
    AI["ChatGPT / Codex / MCP client"] -->|"stdio or private Streamable HTTP"| MCP["CommandBridge MCP"]
    MCP --> POLICY["Shell, command, path and limit policy"]
    POLICY --> HOST["Linux bash/sh or Windows PowerShell/cmd"]

Version 0.2 runs one MCP endpoint per host. A future gateway mode will let host agents initiate outbound connections to one central control plane.

MCP tools

Tool	Purpose
command_bridge_get_system_info	Return OS information and the effective execution policy.
command_bridge_run_command	Execute one bounded command and return exit code, stdout, stderr, timeout and truncation state.

The command tool is annotated as destructive because unrestricted commands can change host state.

Requirements

• Manual installation: Node.js 20 or newer and npm
• One-command Linux installation: a systemd host on x86_64 or arm64 with Linux 4.18+, glibc 2.28+, and libstdc++ 6.0.25+
• At least one supported shell:
  • Linux: bash or sh
  • Windows: Windows PowerShell or cmd.exe
  • PowerShell 7 on Linux is supported through pwsh

One-command Linux systemd install

The pinned v0.2.0 installer deploys CommandBridge under /opt/command-bridge-mcp-server, installs a private Node.js 24.18.0 runtime after verifying the official SHA-256 checksum, creates a low-privilege service account, and enables the service at boot:

installer="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/HsinPu/command-bridge-mcp-server/v0.2.0/install.sh -o "${installer}" && sudo bash "${installer}" && rm -f "${installer}"

The secure defaults are:

• Service: command-bridge-mcp-server.service, enabled and started immediately.
• Account: dedicated command-bridge user with no login, sudo, Docker, or extra groups.
• Endpoint: http://127.0.0.1:8800/mcp with a generated 64-character bearer token.
• Policy: Linux allowlist mode with bash and diagnostic commands only.
• Writable command root: /var/lib/command-bridge-mcp-server/work.
• Configuration: /etc/command-bridge-mcp-server/command-bridge.env, owned by root with mode 0600.

Check the installed service:

sudo systemctl status command-bridge-mcp-server
curl -fsS http://127.0.0.1:8800/health
sudo journalctl -u command-bridge-mcp-server -f

The installer preserves the existing configuration and token when rerun. It uses versioned release directories and rolls the current symlink back if the new service fails its health check.

See Linux systemd installation for prerequisites, directory layout, remote access, configuration, and upgrade behavior.

Manual install and build

cd command-bridge-mcp-server
npm.cmd install
npm.cmd run build

Local stdio usage

stdio is the default transport. An MCP client launches the process on the same host:

{
  "mcpServers": {
    "command-bridge": {
      "command": "node",
      "args": [
        "C:\\path\\to\\command-bridge-mcp-server\\dist\\index.js"
      ],
      "env": {
        "COMMAND_BRIDGE_EXECUTION_MODE": "allowlist"
      }
    }
  }
}

Remote HTTP usage without SSH

Create an environment file on the target host:

COMMAND_BRIDGE_TRANSPORT=http
COMMAND_BRIDGE_BEARER_TOKEN=replace-with-at-least-32-random-characters
COMMAND_BRIDGE_HTTP_HOST=0.0.0.0
COMMAND_BRIDGE_HTTP_PORT=8800
COMMAND_BRIDGE_ALLOWED_HOSTS=100.92.1.7,command-bridge.internal
COMMAND_BRIDGE_EXECUTION_MODE=allowlist

Then start the built server:

npm.cmd start

The endpoint is POST /mcp. Every MCP request must include:

Authorization: Bearer your-token

The unauthenticated GET /health endpoint returns only a basic health state.

Do not expose port 8800 directly to the public internet. Put it on a private network such as Tailscale, or behind an authenticated TLS reverse proxy. The built-in bearer token is an initial deployment control, not a replacement for network isolation and TLS.

Configuration

Variable	Default	Meaning
COMMAND_BRIDGE_TRANSPORT	stdio	stdio or http.
COMMAND_BRIDGE_BEARER_TOKEN	none	Required in HTTP mode; minimum 32 characters.
COMMAND_BRIDGE_HTTP_HOST	127.0.0.1	HTTP bind address.
COMMAND_BRIDGE_HTTP_PORT	8800	HTTP port.
COMMAND_BRIDGE_ALLOWED_HOSTS	none	Comma-separated Host header values; required for non-loopback binds.
COMMAND_BRIDGE_EXECUTION_MODE	allowlist	allowlist or unrestricted.
COMMAND_BRIDGE_ALLOWED_SHELLS	OS defaults	Comma-separated shell names.
COMMAND_BRIDGE_ALLOWED_COMMANDS	OS defaults	Comma-separated command names used in allowlist mode.
COMMAND_BRIDGE_ALLOWED_ROOTS	startup directory	Working-directory roots separated by the OS path delimiter.
COMMAND_BRIDGE_DEFAULT_TIMEOUT_MS	15000	Default command timeout.
COMMAND_BRIDGE_MAX_TIMEOUT_MS	60000	Maximum requested timeout.
COMMAND_BRIDGE_MAX_OUTPUT_CHARS	50000	Combined stdout and stderr limit.
COMMAND_BRIDGE_MAX_PARALLEL_COMMANDS	2	Per-process concurrency limit.
COMMAND_BRIDGE_PASSTHROUGH_ENV	none	Additional environment variable names inherited by child commands.

Linux root lists use a colon:

COMMAND_BRIDGE_ALLOWED_ROOTS=/opt/apps:/var/log/myapp

Windows root lists use a semicolon:

COMMAND_BRIDGE_ALLOWED_ROOTS=C:\Apps;D:\Logs

Execution policy

Allowlist mode:

• Accepts one simple command at a time.
• Rejects pipes, redirects, chaining, command substitution, and newlines.
• Requires the first command name to be configured.
• Still enforces allowed shells, working roots, timeout, output and concurrency limits.

Unrestricted mode:

COMMAND_BRIDGE_EXECUTION_MODE=unrestricted

This permits arbitrary shell syntax and can provide full control available to the operating-system account running CommandBridge. Use a dedicated low-privilege account and require human confirmation in the MCP client.

Child processes inherit only a small baseline environment plus explicitly named variables. The MCP bearer token is not inherited by commands.

Installing when SSH is unavailable

You still need one initial management path to place and start CommandBridge:

• Synology DSM Container Manager or another container UI
• A cloud provider browser console
• Windows RDP, Task Scheduler, Intune, SCCM, or another software deployment system
• A hosting control panel with application deployment

A container controls only what is visible inside that container. Avoid mounting the host root or Docker socket unless that level of access is intentional.

Similar GitHub projects

Project	Approach	Difference from CommandBridge MCP
girishsahu008/mcpshellserver	Local PowerShell plus remote Linux over SSH.	CommandBridge does not require SSH and applies bounded policies to both operating systems.
CrazyMan28/vm-agent-mcp	Cross-platform remote control over Tailscale, including desktop input and administrator access.	CommandBridge starts with command execution only and low-privilege, allowlist-first defaults.
usepowershell/PoshMcp	Dynamically exposes PowerShell cmdlets and modules as MCP tools.	CommandBridge uses a small stable tool surface and also targets Linux shells.
Areso/safe-ssh-mcp	Safety-oriented remote command execution through SSH.	CommandBridge targets environments where SSH is unavailable.

The plain name CommandBridge is already used by unrelated GitHub projects, so this project should always be published and displayed as CommandBridge MCP. The intended repository name is command-bridge-mcp-server.

Verification

npm.cmd test

This builds the TypeScript project and runs the command-policy unit tests.

Roadmap

• Background jobs with polling and cancellation
• Windows service installer
• Structured audit logs with secret redaction
• 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

See SECURITY.md before deploying outside a development environment.