Runner

Clone the mcp-server-runner repository and build it with cargo. The build produces a native binary that starts and manages MCP server child processes.

git clone https://github.com/yonaka15/mcp-server-runner.git
cd mcp-server-runner
cargo build --release

Create a config.json file specifying the MCP server(s) you want to expose. Each entry under 'servers' defines the command and arguments to launch the server process, plus any environment variables it needs.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    }
  },
  "default_server": "filesystem",
  "host": "0.0.0.0",
  "port": 8080
}

Run the binary and point it at your config file. The runner will bind to the configured host and port and wait for WebSocket connections. Enable debug logging with RUST_LOG=debug for verbose output.

RUST_LOG=info ./target/release/mcp-server-runner config.json

Any WebSocket client can now connect to the runner endpoint. The runner forwards MCP JSON-RPC messages between the client and the spawned server process bidirectionally.

// JavaScript WebSocket client example
const ws = new WebSocket('ws://localhost:8080');
ws.onmessage = (event) => console.log('MCP message:', event.data);

For simple single-server setups, configure the runner entirely via environment variables without a config file. PROGRAM sets the executable and ARGS is a comma-separated list of arguments.

export PROGRAM=npx
export ARGS=-y,@modelcontextprotocol/server-github
export PORT=8080
./target/release/mcp-server-runner