Log inSubmit server
Bash Command MCP logo

Bash Command MCP

Runs foreground and background Bash commands through MCP with process controls, logs, configurable execution context, and telemetry.

InstallRepository
Full README Compare alternatives Embed widget Claim this listing

Install Bash Command MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "bash-command-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "bash-command-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 6 tools correctly (6d ago).

Overview

The bash-command-mcp MCP server executes Bash commands locally or through Streamable HTTP, with foreground runs and managed background processes. Its tools accept working-directory and environment overrides, enforce timeout limits, and expose background output through log files. OpenTelemetry traces and metrics are available for tool calls and process lifecycles. Use it when an agent needs controlled shell access, long-running jobs, or command execution inside Docker.

Use cases

  • Run shell commands in a local workspace
  • Launch and monitor long-running background jobs
  • Inspect stdout and stderr from managed processes
  • Execute commands with custom working directories and environment variables
  • Collect command execution telemetry with OpenTelemetry

Key features

  • Foreground Bash command execution
  • Background process lifecycle controls
  • Per-process stdout and stderr logs
  • Working-directory and environment overrides
  • Stdio and Streamable HTTP transports
  • OpenTelemetry traces and metrics

Tools6

What Bash Command MCP lets your agent do. Expand a tool for its parameters.

Verified live~700 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

What it can do

From the 6 tools this server returned when we ran it.

Runs commands · 2Can delete or modify data · 1Read-only tools · 3
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceNot published
Package age240 days
Maintainers1

Observed 2026-10-16 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 12d ago via OSV.dev · bash-command-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads99Package downloads in the last 30 days.
Last commit5mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed6Callable tools this server registers over MCP.
Directory activity3 viewsConfig copies, upvotes, and views on AllMCPs.

How Bash Command MCP works

What bash-command-mcp does

The bash-command-mcp MCP server exposes shell execution through the Model Context Protocol. It can run a command in the foreground, launch a process for later inspection, list tracked background processes, read recent log output, wait for completion, and terminate a tracked process.

Commands execute on the machine or container where the process is running. A direct host installation therefore gives commands the permissions of the user running the server. Docker can provide a separate execution environment, with a host directory mounted at /workspace when files need to be shared.

How the bash-command-mcp MCP server works

The server supports two transports. Stdio is the default for local integrations that start the MCP process. Streamable HTTP is available for network-accessible clients and can listen on a configured host and port. HTTP mode validates the host header by default when bound to a loopback address; an explicit host allow-list is needed when binding to all interfaces.

Foreground execution uses the run tool and returns command results with exit-code behavior. Its timeout defaults to 60 seconds, accepts a minimum of one second, and caps values above 86,400 seconds. Background execution uses run_background, which writes standard output and standard error to log files. Other tools use the process ID to inspect, wait for, or stop that job.

Setup and configuration

Install dependencies with bun install, then start the stdio process with bun run index.ts. The published package can also be launched with npx -y bash-command-mcp. For HTTP, set BASH_COMMAND_MCP_TRANSPORT=http and configure BASH_COMMAND_MCP_HOST and BASH_COMMAND_MCP_PORT. BASH_COMMAND_MCP_ALLOWED_HOSTS controls permitted hostnames when an explicit allow-list is required.

Docker support is provided through the repository image. Build it with docker build -t bash-command-mcp .; a typical local run mounts the current directory to /workspace. HTTP containers need port publishing and should bind to 0.0.0.0 inside the container.

OpenTelemetry is enabled unless OTEL_ENABLED=false. Set OTEL_EXPORTER_OTLP_ENDPOINT to send traces and metrics over OTLP HTTP; without an endpoint, console exporters are used. OTEL_SERVICE_NAME, OTEL_SERVICE_VERSION, OTEL_METRIC_EXPORT_INTERVAL_MS, and BASH_COMMAND_MCP_LOG_DIR provide additional configuration.

Tools and capabilities

  • run: Execute a foreground command with optional cwd, env, and timeout settings.
  • run_background: Start a command asynchronously and record its output in log files.
  • list_background: Show tracked jobs and their log-file paths.
  • tail_background: Return the last requested number of log lines, up to 5,000.
  • wait_background: Wait for a job and return its final status and output.
  • kill_background: Stop a tracked process by PID.

The bash-command-mcp MCP server instruments all listed tools with OpenTelemetry spans. It also records background start and end activity plus tool-call, failure, timeout, and duration metrics.

Limitations and notes

Shell commands can modify the host, access available files, and use the server process's permissions. Do not run the bash-command-mcp MCP server directly on a host unless the MCP client and prompts are trusted. Docker reduces host exposure, but mounted directories remain writable from the container and changes are reflected on the host.

Background jobs are tracked by process ID and depend on the server's log directory. HTTP exposure also requires deliberate host binding, port configuration, and host validation settings; binding beyond localhost without an appropriate allow-list can expose command execution to unintended clients.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Bash Command MCP

bash-command-mcp is an MCP server that connects AI clients to Bash on the machine or container where it runs. Its main tools execute foreground commands, start background jobs, list processes, inspect logs, wait for completion, and kill tracked processes, with optional working-directory, environment, timeout, and telemetry settings.

Install dependencies with `bun install`, then start it using `bun run index.ts`; the published package can also run with `npx -y bash-command-mcp`. For isolation, build and run the supplied Docker image, optionally mounting a local directory at `/workspace`.

Set `BASH_COMMAND_MCP_TRANSPORT=http`, configure `BASH_COMMAND_MCP_HOST` and `BASH_COMMAND_MCP_PORT`, and run the server. In Docker, bind to `0.0.0.0` and publish the port. If the service is exposed beyond localhost, configure `BASH_COMMAND_MCP_ALLOWED_HOSTS` with permitted hostnames.

Yes, bash-command-mcp supports background commands through `run_background`, `list_background`, `tail_background`, `wait_background`, and `kill_background`. Output is written to log files, and jobs are managed using their process IDs.

Run it directly on a host only when the MCP client and prompts are fully trusted. Commands execute with the server process's user permissions, so the documented safer isolation approach is to run the server in Docker.

Related MCP servers

All in Command Line All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewBash Command MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/bash-command-mcp?style=directory)](https://allmcps.com/mcp/bash-command-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/bash-command-mcp"><img src="https://allmcps.com/api/badge/bash-command-mcp?style=directory" alt="Bash Command MCP on AllMCPs" /></a>