CommandBridge MCP

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.

Related MCP server: mcp-shell

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

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

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

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.