{
  "markdown": "# bash-command-mcp\n\nA highly sophisticated Bash MCP server for safe, structured command execution with first-class background job orchestration.\n\n## Important Security Warning\n\nThis server executes shell commands on the machine where it is running.\n\nIf you run `bun run index.ts` directly on your host, commands run on your host with your user permissions.\nUse Docker to isolate execution unless you fully trust the MCP client and prompts.\n\nTo install dependencies:\n\n```bash\nbun install\n```\n\nTo run over stdio:\n\n```bash\nbun run index.ts\n```\n\nTo run over Streamable HTTP:\n\n```bash\nBASH_COMMAND_MCP_TRANSPORT=http \\\nBASH_COMMAND_MCP_HOST=127.0.0.1 \\\nBASH_COMMAND_MCP_PORT=3000 \\\nbun run index.ts\n```\n\nTo run via npm/npx (published package):\n\n```bash\nnpx -y bash-command-mcp\n```\n\n## Why This Server\n\n- High-fidelity shell execution with clear exit-code semantics.\n- Advanced background process lifecycle controls (`run_background`, `wait_background`, `kill_background`).\n- Built-in observability via per-process stdout/stderr log files.\n- OpenTelemetry traces and metrics for production visibility.\n- Agent-friendly ergonomics with `cwd` and `env` overrides for precise execution context.\n\n## Tool Behavior\n\nTools:\n- `run`: run command in foreground.\n  Args: `command` or `cmd`, `timeoutSeconds` (default `60`, min `1`; values above `86400` are capped with a hint), optional `cwd`, optional `env`.\n- `run_background`: start command in background with stdout/stderr written to log files.\n  Args: `command` or `cmd`, optional `cwd`, optional `env`.\n- `list_background`: list tracked background processes, including log file paths.\n- `kill_background`: stop tracked background process by `pid`.\n- `tail_background`: show last N lines from background process logs.\n  Args: `pid`, optional `lines` (default `200`, max `5000`).\n- `wait_background`: wait for background process completion and return final status/output.\n  Args: `pid`, optional `timeoutSeconds` (default `60`, min `1`; values above `86400` are capped with a hint).\n## OpenTelemetry\n\nThis server includes built-in OpenTelemetry instrumentation for traces and metrics.\n\n- OpenTelemetry packages are installed with the server package.\n- Telemetry initializes unless `OTEL_ENABLED=false`.\n- If `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces/metrics are exported via OTLP HTTP.\n- If no OTLP endpoint is configured, console exporters are used.\n\nInstrumented operations:\n- Tool call spans for `run`, `run_background`, `list_background`, `tail_background`, `wait_background`, and `kill_background`.\n- Background lifecycle spans/counters (`started`, `ended`).\n- Metrics for tool calls, failures, timeouts, and duration histograms.\n\nCommon env vars:\n- `OTEL_ENABLED=true|false`\n- `OTEL_SERVICE_NAME=bash-command-mcp`\n- `OTEL_SERVICE_VERSION=1.0.0`\n- `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`\n- `OTEL_METRIC_EXPORT_INTERVAL_MS=10000`\n- `BASH_COMMAND_MCP_LOG_DIR=/path/to/log-dir`\n\nExample (OTLP Collector on localhost):\n\n```bash\nOTEL_ENABLED=true \\\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \\\nOTEL_SERVICE_NAME=bash-command-mcp \\\nnpx -y bash-command-mcp\n```\n\n## Transports\n\nThis server supports two transports:\n\n- `stdio` for local, process-spawned integrations.\n- `http` for remote or network-accessible MCP clients using Streamable HTTP.\n\nDefault behavior remains `stdio` so existing desktop and CLI setups keep working.\n\nEnvironment variables for HTTP mode:\n\n- `BASH_COMMAND_MCP_TRANSPORT=http|stdio`\n- `BASH_COMMAND_MCP_HOST=127.0.0.1`\n- `BASH_COMMAND_MCP_PORT=3000`\n- `BASH_COMMAND_MCP_ALLOWED_HOSTS=localhost,127.0.0.1,[::1]`\n\nHTTP 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`.\n\n\n## Docker\n\nBuild the image:\n\n```bash\ndocker build -t bash-command-mcp .\n```\n\nRun with a local folder mounted at `/workspace`:\n\n```bash\ndocker run --rm -i -v \"$(pwd):/workspace\" bash-command-mcp\n```\n\nRun over Streamable HTTP:\n\n```bash\ndocker run --rm -p 3000:3000 \\\n  -e BASH_COMMAND_MCP_TRANSPORT=http \\\n  -e BASH_COMMAND_MCP_HOST=0.0.0.0 \\\n  -e BASH_COMMAND_MCP_PORT=3000 \\\n  bash-command-mcp\n```\n\n`/workspace` mapping explained:\n- Left side (`$(pwd)`) is a folder on your host machine.\n- Right side (`/workspace`) is the path inside the container.\n- Commands run by this MCP server should target files under `/workspace`; those changes are written back to the mapped host folder.\n\nFor 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.\n\nExample:\n- 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`.\n",
  "bytes": 4824,
  "sha": "ec015443dfa475894c3bf2511c1957b2f6b19a1380b27a1a7ffbfc9d92f15605",
  "repo_slug": "mrorigo/bash-command-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrorigo_bash_command_mcp_6ecbab89/readme"
}