The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Bash Command MCP listing page.
A highly sophisticated Bash MCP server for safe, structured command execution with first-class background job orchestration.
This server executes shell commands on the machine where it is running.
If you run bun run index.ts directly on your host, commands run on your host with your user permissions.
Use Docker to isolate execution unless you fully trust the MCP client and prompts.
To install dependencies:
To run over stdio:
To run over Streamable HTTP:
To run via npm/npx (published package):
run_background, wait_background, kill_background).cwd and env overrides for precise execution context.Tools:
run: run command in foreground.
Args: command or cmd, timeoutSeconds (default 60, min 1; values above 86400 are capped with a hint), optional cwd, optional env.run_background: start command in background with stdout/stderr written to log files.
Args: command or cmd, optional cwd, optional env.list_background: list tracked background processes, including log file paths.kill_background: stop tracked background process by pid.tail_background: show last N lines from background process logs.
Args: pid, optional lines (default 200, max 5000).wait_background: wait for background process completion and return final status/output.
Args: pid, optional timeoutSeconds (default 60, min 1; values above 86400 are capped with a hint).This server includes built-in OpenTelemetry instrumentation for traces and metrics.
OTEL_ENABLED=false.OTEL_EXPORTER_OTLP_ENDPOINT is set, traces/metrics are exported via OTLP HTTP.Instrumented operations:
run, run_background, list_background, tail_background, wait_background, and kill_background.started, ended).Common env vars:
OTEL_ENABLED=true|falseOTEL_SERVICE_NAME=bash-command-mcpOTEL_SERVICE_VERSION=1.0.0OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318OTEL_METRIC_EXPORT_INTERVAL_MS=10000BASH_COMMAND_MCP_LOG_DIR=/path/to/log-dirExample (OTLP Collector on localhost):
This server supports two transports:
stdio for local, process-spawned integrations.http for remote or network-accessible MCP clients using Streamable HTTP.Default behavior remains stdio so existing desktop and CLI setups keep working.
Environment variables for HTTP mode:
BASH_COMMAND_MCP_TRANSPORT=http|stdioBASH_COMMAND_MCP_HOST=127.0.0.1BASH_COMMAND_MCP_PORT=3000BASH_COMMAND_MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]HTTP mode uses host-header validation by default when bound to a loopback address. If you bind to 0.0.0.0 or ::, provide an explicit allow-list in BASH_COMMAND_MCP_ALLOWED_HOSTS.
Build the image:
Run with a local folder mounted at /workspace:
Run over Streamable HTTP:
/workspace mapping explained:
$(pwd)) is a folder on your host machine./workspace) is the path inside the container./workspace; those changes are written back to the mapped host folder.For HTTP mode in Docker, bind to 0.0.0.0 and publish the port with -p. If you expose the container beyond localhost, set BASH_COMMAND_MCP_ALLOWED_HOSTS to the hostnames you want to permit.
Example:
./project/file.txt and you run the container from ./project, the same file is available in the container at /workspace/file.txt.