Bash Command Mcp
Runs shell commands on your local machine or in a container with full lifecycle control over background processes. You get six tools: run commands in the foreground with configurable timeouts, spin up background jobs that write to log files, tail those logs, wait for completion, kill processes, and list everything running. Built in OpenTelemetry tracing and metrics if you point it at a collector. Supports stdio for local Claude Desktop integration or HTTP transport for remote access. The Docker setup is clean: mount a volume at /workspace and commands execute in isolation. Useful when you need programmatic shell access with proper job control instead of fire and forget execution.
- GitHub stars
- 1
- tools
- 6
- transport
- STDIO
- env vars
- 6
- last updated
- Feb 17, 2026
Tools
6 toolsPublic tool metadata for what this MCP can expose to an agent.
runrun command in foreground.
run command in foreground.
No parameter schema in public metadata yet.
run_backgroundstart command in background with stdout/stderr written to log files.
start command in background with stdout/stderr written to log files.
No parameter schema in public metadata yet.
list_backgroundlist tracked background processes, including log file paths.
list tracked background processes, including log file paths.
No parameter schema in public metadata yet.
kill_backgroundstop tracked background process by `pid`.
stop tracked background process by `pid`.
No parameter schema in public metadata yet.
tail_backgroundshow last N lines from background process logs.
show last N lines from background process logs.
No parameter schema in public metadata yet.
wait_backgroundwait for background process completion and return final status/output.
wait for background process completion and return final status/output.
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageConfiguration
OTEL_ENABLEDEnable or disable OpenTelemetry instrumentation (`true` or `false`).
OTEL_SERVICE_NAMEOpenTelemetry service name override.
OTEL_SERVICE_VERSIONOpenTelemetry service version override.
OTEL_EXPORTER_OTLP_ENDPOINTOTLP HTTP endpoint for exporting OpenTelemetry traces and metrics (for example `http://localhost:4318`).
OTEL_METRIC_EXPORT_INTERVAL_MSOpenTelemetry metrics export interval in milliseconds.
BASH_COMMAND_MCP_LOG_DIRDirectory used to store background process stdout/stderr log files.
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:
bun install
To run over stdio:
bun run index.ts
To run over Streamable HTTP:
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):
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
cwdandenvoverrides for precise execution context.
Details
- Repository
- github.com/mrorigo/bash-command-mcp
- Category
- Developer Tools
- Package
bash-command-mcp- Transport
- STDIO
- Registry
- MCP registry, active
More from mrorigo
Related Developer Tools MCP servers
View all
Wisegitsandip124/wisegitExtracts decision intent from git history and protects intentional code from AI modification.1stars
repowardsanoy24/repowardGitHub MCP server that blocks private-to-public leaks by agents, with approvals and audit.1stars
Promptlint MCPsean-sunagaku/promptlint-mcpStatic linter for AI prompts: contradictions, redundancy, ambiguity, and fluff.1stars
DEPRECATEDtencent-lexiang/lexiang-mcp-serverDEPRECATED: Please use io.github.tencent-lexiang/lexiang-mcp-server instead.1stars
Gmemyksanjo/gmemPersistent, Solana-aware project memory for AI coding agents. Typed entities + git-aware diffs.1stars
Repo Memoryyubinkim444/repo-memoryShared, git-tracked working memory for AI agents on the same codebase.1stars