Bash

Executes bash commands via MCP and returns stdout, stderr, exit code, and duration for each run.

python

0

GitHub Stars

python

Language

3 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "nimblebraininc-mcp-bash": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "mcp_bash.server"
      ]
    }
  }
}

Bash MCP Server lets you run arbitrary bash commands through a Model Context Protocol client and receive structured results, including stdout, stderr, exit code, and how long execution took. It’s useful for automating shell tasks, integrating command execution into larger workflows, or testing scripts in a controlled MCP environment.

How to use

You interact with the server by calling the provided tool (bash_exec) through your MCP client. You supply the bash command you want to run, and you receive a JSON response containing stdout, stderr, the exit code, and the duration of execution. This enables you to programmatically execute shell commands and react to their results within your MCP-powered automation.

How to install

Prerequisites: You need a working environment capable of installing and running MCP servers, including the MPACK registry client that handles MCP deployments.

mpak install @nimblebraininc/bash

Claude integration options are available for adding this MCP server. You can instruct Claude to register the server using the following commands.

claude mcp add bash -- mpak run @nimblebraininc/bash

If you are configuring Claude Desktop, add the MCP server to your claude_desktop_config.json like this.

{
  "mcpServers": {
    "bash": {
      "command": "mpak",
      "args": ["run", "@nimblebraininc/bash"]
    }
  }
}

Additional sections

Security model: The server executes arbitrary bash commands. Security is enforced by deployment boundaries rather than a built-in allowlist or sandbox. The deployment environment constrains what commands can do.

Quick start for local development and testing is available via standard Python/UV runtimes and MCP tooling.

Security model

The server executes arbitrary bash commands. Security is enforced by deployment boundaries rather than a built-in allowlist or sandbox. The deployment environment constrains what commands can do.

Development

For development and testing, you can run the server locally using the provided commands. Use the following pattern to start the server in stdio mode.

uv run python -m mcp_bash.server

Or start via FastMCP as an alternative.


## Available tools

### bash\_exec

Execute a bash command and obtain stdout, stderr, exit code, and duration. You provide the command, an optional working directory, an optional timeout in seconds (default 30, max 600), and optional environment variables to set for that execution.