bash-command-mcp

You can safely execute and manage shell commands using this MCP server, which orchestrates foreground and background processes with clear lifecycle controls, logging, and observability to help you automate complex command workflows.

How to use

You operate this MCP server from a client that issues defined tool calls to run commands, start background processes, inspect logs, and wait for completion. Use the standard workflow to run a command in the foreground, or manage long-running background tasks with explicit control over their lifecycle and log output.

How to install

Prerequisites: you need Node.js installed on your host if you plan to run the MCP server directly, or you can run it inside a container. The project also relies on a modern JavaScript runtime such as Bun for quick startup and dependency management.

Install dependencies with Bun, then start the server locally:

bun install

bun run index.ts

Additional setup options

If you prefer using the published package via npm or npx, you can start the MCP server with a single command. This approach runs the server in your environment using the package’s entry point.

npx -y bash-command-mcp

Docker usage

You can isolate execution by running the MCP server inside Docker. Build the image and run it with a local workspace mounted, so commands operate on files in your host project.

docker build -t bash-command-mcp .

docker run --rm -i -v "$(pwd):/workspace" bash-command-mcp

Observability and telemetry

The server includes OpenTelemetry instrumentation that records traces and metrics for tool calls and background processes. Telemetry is enabled by default unless you disable it via environment variables.

If you configure an OTLP endpoint, traces and metrics are exported to that endpoint; otherwise, you will see console exporters.

Important environment considerations

Security note: this MCP server executes shell commands on the machine where it runs. To avoid running commands on your host in untrusted environments, run the server inside Docker to isolate execution.

Key environment variables you may set to customize telemetry and logging include OTEL_ENABLED, OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_METRIC_EXPORT_INTERVAL_MS, and BASH_COMMAND_MCP_LOG_DIR.

What you can do with Tools

This server exposes commands to manage shell execution and background processes with clear status and logs. You can run commands in the foreground, start and monitor background processes, list live background jobs, tail their logs, wait for completion, and terminate processes when needed.

Security and usage notes

Only run this MCP server in trusted environments or isolated containers. Understand that the server will perform shell operations with your user permissions, so review prompts and arguments before execution.

Troubleshooting and notes

If you encounter issues starting the server, verify your runtime (Node or Bun), ensure dependencies are installed, and confirm that your environment variables are correctly set for telemetry if you rely on OpenTelemetry exporting.

Available tools

run

Execute a command in the foreground with optional cwd and environment overrides, and a timeout.

run_background

Start a command in the background and write stdout and stderr to log files for later inspection.

list_background

List all tracked background processes along with their log file paths and statuses.

kill_background

Terminate a tracked background process by its PID.

tail_background

Show the last N lines from a background process log file, defaulting to 200 lines.

wait_background

Wait for a background process to finish and return its final status and output.