async-bash-mcp

English | 中文

An MCP server for spawning and managing bash commands asynchronously. Run multiple shell commands in parallel and check their progress independently.

Background

I discovered the original async-bash-mcp project while struggling with opencode's bash execution timeouts. The original project effectively solves this problem — it's especially useful for time-consuming operations like downloading and installing project dependencies, where fixed timeouts often fall short. This Rust rewrite was built using opencode + oh-my-opencode inside OpenChamber. As a local-type MCP server, Rust offers lower startup overhead compared to Python, making it a better fit for tools that are launched on every session.

Usage with opencode

Add to your opencode.json config to replace the bash tool with async-bash-mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "bash": false
  },
  "mcp": {
    "async-bash": {
      "type": "local",
      "command": ["/path/to/async-bash-mcp"],
      "enabled": true
    }
  }
}

Download the latest binary from GitHub Releases or build from source with cargo build --release.

Then use commands like:

• "Spawn a long-running build in the background"
• "Run tests in parallel and show me the results"
• "Start a server and tell me when it's ready"

Why async bash?

When working with long-running commands like builds, tests, or servers, the agent needs to:

• Monitor progress incrementally without committing to a fixed timeout
• Run multiple commands in parallel and check each independently
• Make decisions about continuing or terminating based on partial output
• Process real-time feedback as commands generate output

This tool provides the agent with better information for decision-making, leading to faster task completion and fewer confused responses.

Key advantages over the built-in bash tool:

• Better decision making: Agents can see partial output and make informed choices about continuing or terminating
• Parallel execution: Run multiple commands simultaneously
• No timeout guessing: Check progress incrementally instead of setting timeouts upfront
• Faster iterations: No waiting for arbitrary timeouts when errors are already visible

This tool is designed to replace opencode's bash tool for any scenario involving potentially long-running commands, giving agents the information they need to make better decisions and save you time.

Tools

spawn - Launch a bash command asynchronously

• command (str): The bash command to run
• cwd (str, optional): Working directory path
• Returns a process ID for tracking

list_processes - Show all running/recent processes

• No parameters
• Returns array of {"ID": int, "command": str, "done": bool}

poll - Check progress of a spawned process

• process_id (int): ID from spawn command
• wait (int): Wait time in milliseconds
• terminate (bool, optional): Kill process before returning results
• Returns {"stdout": str, "stderr": str, "elapsedTime": float, "finished": bool, "exitCode": int}

Installation

Download the pre-built binary from GitHub Releases, or build from source:

cargo build --release
# Binary will be at: target/release/async-bash-mcp

macOS Note

If you downloaded the binary from GitHub Releases, macOS Gatekeeper may block it from running. Remove the quarantine attribute first:

xattr -d com.apple.quarantine /path/to/async-bash-mcp