sandbox-mcp-server

Docker sandbox MCP server with per-session containers. Each MCP session gets its own isolated Docker container with a dedicated data directory mounted as /home/user.

Features

• Per-session containers — each session gets its own Docker container (sandbox-{session_id})
• Isolated data — data_dir/sessions/{session_id}/ mounted as /home/user in container
• 9 MCP tools — file operations, editor operations, and shell commands
• Dual transport — stdio (default) or HTTP mode via --transport flag
• HTTP authentication — Bearer token auth and session management
• Session resumption — reconnect to a previous session by ID, preserving files on disk
• Automatic cleanup — containers are removed when sessions end or server shuts down

Architecture

Single crate, seven source modules:

Requirements

• Docker daemon running locally
• Docker images pulled (default: debian:latest)

CLI

sandbox-mcp-server [OPTIONS]

Options:
  --image <IMAGE>        Docker image [default: debian:latest]
  --data-dir <PATH>      Base data directory [default: XDG_DATA_HOME/sandbox-mcp-server]
  --timeout <MS>         Shell command timeout in ms [default: 60000]
  --max-output <BYTES>   Max shell output bytes [default: 65536]
  --transport <MODE>     stdio or http [default: stdio]
  --host <HOST>          HTTP bind address [default: 127.0.0.1]
  --port <PORT>          HTTP port [default: 8080]
  --auth <TOKEN>         Bearer token for HTTP auth
  --session-id <UUID>    Resume an existing session by ID (stdio only)
  --version              Print version

Build

Prerequisites

• Rust toolchain (stable)
• Docker (for runtime, not build)

Build

cargo build --release

With Nix

nix develop   # reproducible dev environment with git hooks
nix build     # build package

MCP Tools

File operations

• file_read — read a file and return its contents
• file_write — create or overwrite a file (parent directory must exist)
• file_list — list directory contents (directories have trailing /)

Editor operations

• editor_search — search for text in a file, returns matching lines with line numbers
• editor_replace — replace a unique substring (fails if ambiguous or not found)
• editor_replace_lines — replace a range of lines [start, end] inclusive (1-indexed)

Shell operations

• shell_exec — execute a command and return output
• shell_spawn — spawn a background process (detached)
• shell_kill — kill a process by PID

MCP Protocol

Stdio Transport

One JSON-RPC 2.0 object per line on stdin/stdout. A session is created automatically on startup.

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | cargo run

To resume a previous session, pass --session-id with the UUID from a prior run:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | \
  cargo run -- --session-id 550e8400-e29b-41d4-a716-446655440000

HTTP Transport

cargo run -- --transport http --port 8080 --auth secret123

Initialize (creates session, returns Mcp-Session-Id header):

curl -s -D- -X POST http://127.0.0.1:8080/mcp

... [View full README on GitHub](https://github.com/nizovtsevnv/sandbox-mcp-server#readme)