How do I use Bash MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Bash MCP Server list all files in the current directory including hidden ones" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Bash MCP Server

mpak NimbleBrain Discord License: MIT

A Model Context Protocol (MCP) server that executes bash commands. Returns stdout, stderr, exit code, and execution duration for each command.

View on mpak registry | Built by

Install

Install with mpak:

mpak install @nimblebraininc/bash

Claude Code

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

Claude Desktop

Add to your claude_desktop_config.json:

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

See the mpak registry page for full install options.

Tools

bash_exec

Execute a bash command and return stdout, stderr, exit code, and duration.

Parameter	Type	Required	Description
`command`	`string`	Yes	The bash command to execute
`cwd`	`string`	No	Working directory (defaults to server's cwd)
`timeout`	`integer`	No	Timeout in seconds (default: `30`, max: `600`)
`env`	`object`	No	Additional environment variables to set

Example call:

{ "name": "bash_exec", "arguments": { "command": "ls -la /tmp", "timeout": 10 } }

Example response:

{ "stdout": "total 0\ndrwxrwxrwt 12 root wheel 384 Jan 15 12:00 .\ndrwxr-xr-x 6 root wheel 192 Jan 1 00:00 ..\n", "stderr": "", "exit_code": 0, "duration_ms": 12 }

Security Model

This server executes arbitrary bash commands. Security is secure-by-deployment: the server itself has no allowlist or sandbox. Instead, security is enforced by the deployment environment:

mpak: User approves MTF permissions (subprocess: "full") at install time
Containers: Linux namespaces, cgroups, and network policies restrict what commands can do
Claude Desktop: Runs under the user's own OS permissions

The MTF permission declaration (subprocess: "full", filesystem: "full", network: "full") accurately reflects that bash commands can read/write files and make network calls.

Quick Start

Local Development

git clone https://github.com/NimbleBrainInc/mcp-bash.git cd mcp-bash # Install dependencies uv sync # Run the server (stdio mode) uv run python -m mcp_bash.server # Or run via FastMCP uv run fastmcp run src/mcp_bash/server.py

The server supports HTTP transport with:

Health check: GET /health
MCP endpoint: POST /mcp

Development

# Install with dev dependencies uv sync --group dev # Run unit tests make test # Run with coverage make test-cov # Run all checks (format, lint, typecheck, unit tests) make check # Format uv run ruff format . # Lint uv run ruff check .

E2E Tests

End-to-end tests validate the full MCPB bundle lifecycle: building the bundle, deploying it into a Docker container, and calling tools over HTTP.

Prerequisites: Docker running, mcpb CLI installed (npm install -g @anthropic-ai/mcpb)

make test-e2e

The tests:

Vendor dependencies for the Docker container's Linux architecture
Build a .mcpb bundle with mcpb pack
Serve the bundle over HTTP
Start a nimbletools/mcpb-python container that downloads and runs the bundle
Verify the /health endpoint, MCP tool listing, and tool invocation via streamable HTTP