io.github.mrorigo/bash-command-mcp
Sophisticated bash command MCP server that runs and manages shell execution.
Open source Open in the app JSON README (API)
About
Sophisticated bash command MCP server that runs and manages shell execution.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- mrorigo
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Stars
- 2
- Last push
- 2026-05-21T06:50:34Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:51
- Updated
- 2026-08-29 04:00:51
- Origin id
io.github.mrorigo/bash-command-mcp
README
# bash-command-mcp A highly sophisticated Bash MCP server for safe, structured command execution with first-class background job orchestration. ## Important Security Warning 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: ```bash bun install ``` To run over stdio: ```bash bun run index.ts ``` To run over Streamable HTTP: ```bash BASH_COMMAND_MCP_TRANSPORT=http \ BASH_COMMAND_MCP_HOST=127.0.0.1 \ BASH_COMMAND_MCP_PORT=3000 \ bun run index.ts ``` To run via npm/npx (published package): ```bash npx -y bash-command-mcp ``` ## Why This Server - High-fidelity shell execution with clear exit-code semantics. - Advanced background process lifecycle controls (`run_background`, `wait_background`, `kill_background`). - Built-in observability via per-process stdout/stderr log files. - OpenTelemetry traces and metrics for production visibility. - Agent-friendly ergonomics with `cwd` and `env` overrides for precise execution context. ## Tool Behavior 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). ## OpenTelemetry This server includes built-in OpenTelemetry instrumentation for traces and metrics. - OpenTelemetry packages are installed with the server package. - Telemetry initializes unless `OTEL_ENABLED=false`. - If `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces/metrics are exported via OTLP HTTP. - If no OTLP endpoint is configured, console exporters are used. Instrumented operations: - Tool call spans for `run`, `run_background`, `list_background`, `tail_background`, `wait_background`, and `kill_background`. - Background lifecycle spans/counters (`started`, `ended`). - Metrics for tool calls, failures, timeouts, and duration histograms. Common env vars: - `OTEL_ENABLED=true|false` - `OTEL_SERVICE_NAME=bash-command-mcp` - `OTEL_SERVICE_VERSION=1.0.0` - `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` - `OTEL_METRIC_EXPORT_INTERVAL_MS=10000` - `BASH_COMMAND_MCP_LOG_DIR=/path/to/log-dir` Example (OTLP Collector on localhost): ```bash OTEL_ENABLED=true \ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \ OTEL_SERVICE_NAME=bash-command-mcp \ npx -y bash-command-mcp ``` ## Transports 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|stdio` - `BASH_COMMAND_MCP_HOST=127.0.0.1` - `BASH_COMMAND_MCP_PORT=3000` - `BASH_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`. ## Docker Build the image: ```bash docker build -t bash-command-mcp . ``` Run with a local folder mounted at `/workspace`: ```bash docker run --rm -i -v "$(pwd):/workspace" bash-command-mcp ``` Run over Streamable HTTP: ```bash docker run --rm -p 3000:3000 \ -e BASH_COMMAND_MCP_TRANSPORT=http \ -e BASH_COMMAND_MCP_HOST=0.0.0.0 \ -e BASH_COMMAND_MCP_PORT=3000 \ bash-command-mcp ``` `/workspace` mapping explained: - Left side (`$(pwd)`) is a folder on your host machine. - Right side (`/workspace`) is the path inside the container. - Commands run by this MCP server should target files under `/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: - If your host has `./project/file.txt` and you run the container from `./project`, the same file is available in the container at `/workspace/file.txt`.