io.github.mrorigo/bash-command-mcp

Official

by mrorigo · TypeScript

Sophisticated bash command MCP server that runs and manages shell execution.

Executes and manages shell commands with sophisticated bash command handling.

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.

Install

Configuration

Environment variables

OTEL_ENABLED

Enable or disable OpenTelemetry instrumentation (`true` or `false`).

OTEL_SERVICE_NAME

OpenTelemetry service name override.

OTEL_SERVICE_VERSION

OpenTelemetry service version override.

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP HTTP endpoint for exporting OpenTelemetry traces and metrics (for example `http://localhost:4318`).

OTEL_METRIC_EXPORT_INTERVAL_MS

OpenTelemetry metrics export interval in milliseconds.

BASH_COMMAND_MCP_LOG_DIR

Directory used to store background process stdout/stderr log files.

claude_desktop_config.json

{
  "mcpServers": {
    "bash-command-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "bash-command-mcp@0.1.0"
      ],
      "env": {
        "OTEL_ENABLED": "<YOUR_OTEL_ENABLED>",
        "OTEL_SERVICE_NAME": "<YOUR_OTEL_SERVICE_NAME>",
        "OTEL_SERVICE_VERSION": "<YOUR_OTEL_SERVICE_VERSION>",
        "OTEL_EXPORTER_OTLP_ENDPOINT": "<YOUR_OTEL_EXPORTER_OTLP_ENDPOINT>",
        "OTEL_METRIC_EXPORT_INTERVAL_MS": "<YOUR_OTEL_METRIC_EXPORT_INTERVAL_MS>",
        "BASH_COMMAND_MCP_LOG_DIR": "<YOUR_BASH_COMMAND_MCP_LOG_DIR>"
      }
    }
  }
}