Bash MCP Server (bash-mcp)

A Model Context Protocol (MCP) server that provides robust Bash execution capabilities across Windows, macOS, and Linux. Built with Python 3.12+ and managed with uv.

---

Key Features

• Cross-Platform Multi-Runtime Support:
  • Windows: Automatically detects and supports Git Bash (C:\Program Files\Git\bin\bash.exe), WSL (Windows Subsystem for Linux), and MSYS2.
  • macOS / Linux: Native POSIX bash.
  • Custom Override: Override runtime with the BASH_PATH environment variable across all platforms. The target executable is expected to implement Bash semantics and accept standard -c <command> arguments.
• Process Lifecycle Management & Containment Model:
  • Windows (Git Bash / MSYS2): Windows Job assignment is best-effort and occurs immediately after process creation; a short pre-assignment execution window exists. Processes assigned to the dedicated Windows Job Object (JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE) have termination attempts performed on their entire process tree on timeout, cancellation, or error.
  • WSL (Linux VM): Employs PID-marker-based process-group signaling and clean group termination (SIGTERM -> SIGKILL) to terminate background Linux processes inside the VM on timeout or cancellation. (Note: commands that detach into independent sessions via setsid or modify supervisor markers require container-level isolation such as Docker/cgroups for full sandbox containment).
  • POSIX (macOS / Linux): Creates isolated process groups (start_new_session=True) and performs phased shutdown (SIGTERM -> 0.2s grace interval -> SIGKILL).
  • Cancellation-Safe: Shielded cleanup performs bounded reader-drain and process-reap attempts, and closes pipe transports even under repeated task cancellation.
• Exact Bash Semantics:
  • WSL commands are passed directly as raw positional parameters without outer shell interpolation, preserving exact variable scoping, literal single-quotes, and quoted heredocs.
• PE Binary Screening:
  • Checks expected DOS/PE signatures (MZ, PE\0\0) for Windows binary executables, rejecting plain-text or corrupt files.
• Bounded Stream Capture & Truncation Metadata:
  • Streams are drained concurrently with per-stream byte limits (default 1 MB) to prevent unbounded memory consumption from noisy commands.
  • Output truncation is clearly indicated in results with byte-accurate counts.
  • Partial output emitted prior to timeouts is preserved.
• Modern Transport Protocols:
  • stdio (default, recommended for local clients like Antigravity, Claude Desktop, Cursor).
  • streamable-http (recommended modern network transport).
  • sse (legacy network transport).
  • Strict loopback protection: only canonical loopback addresses (127.0.0.1, localhost, ::1) are permitted without explicit --allow-remote opt-in.

---

Exposed Tools

1. execute_bash

Executes a Bash command, pipeline, or multi-line script.

Parameter	Type	Default	Description
command	string	(required)	The Bash command or multi-line script to run.
cwd	string	null	Working directory. Accepts Windows paths or native POSIX paths (e.g. /tmp under WSL).
timeout_seconds	integer	120	Execution timeout in seconds (must be between 1 and 3600).
env_type	string	"auto"	Execution environment ("auto", "git_bash", "wsl", "msys2", "native", "custom").

Tool Annotations:

• destructive_hint=True
• open_world_hint=True
• read_only_hint=False

2. get_bash_environments

Returns diagnostic details about all detected Bash runtimes, executable paths, and the active default environment.

---

Installation & Setup

Ensure uv is installed.

# Clone or navigate to the repository
cd bash-mcp

# Install dependencies and sync the virtual environment
uv sync

---

Running the Server

Stdio Transport (Default)

uv run bash-mcp

Streamable HTTP Transport (Recommended for Network)

uv run bash-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Legacy SSE Transport

uv run bash-mcp --transport sse --host 127.0.0.1 --port 8000

Security Note: Binding to non-loopback interfaces requires passing --allow-remote. Because command execution runs with host user privileges, network deployments should be secured with TLS, authentication proxies, or container isolation.

---

Integrating with Antigravity / MCP Clients

Antigravity Global Configuration (~/.gemini/config/mcp_config.json)

{
  "mcpServers": {
    "bash": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\User\\stuff\\bash-mcp",
        "run",
        "bash-mcp"
      ]
    }
  }
}

---

Running Tests

Run the test suite with pytest:

uv run pytest