# Bash MCP Server
[](https://mpak.dev/packages/@nimblebraininc/bash?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)
[](https://nimblebrain.ai?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)
[](https://nimblebrain.ai/discord?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)
[](LICENSE)
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that executes bash commands. Returns stdout, stderr, exit code, and execution duration for each command.
**[View on mpak registry](https://mpak.dev/packages/@nimblebraininc/bash?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)** | **Built by [NimbleBrain](https://nimblebrain.ai?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)**
## Install
Install with [mpak](https://mpak.dev?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash):
```bash
mpak install @nimblebraininc/bash
```
### Claude Code
```bash
claude mcp add bash -- mpak run @nimblebraininc/bash
```
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"bash": {
"command": "mpak",
"args": ["run", "@nimblebraininc/bash"]
}
}
}
```
See the [mpak registry page](https://mpak.dev/packages/@nimblebraininc/bash?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash) 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:**
```json
{
"name": "bash_exec",
"arguments": {
"command": "ls -la /tmp",
"timeout": 10
}
}
```
**Example response:**
```json
{
"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
```bash
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
```bash
# 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`)
```bash
make test-e2e
```
The tests:
1. Vendor dependencies for the Docker container's Linux architecture
2. Build a `.mcpb` bundle with `mcpb pack`
3. Serve the bundle over HTTP
4. Start a `nimbletools/mcpb-python` container that downloads and runs the bundle
5. Verify the `/health` endpoint, MCP tool listing, and tool invocation via streamable HTTP
## About
Bash MCP Server is published on the [mpak registry](https://mpak.dev?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash) and built by [NimbleBrain](https://nimblebrain.ai?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash). mpak is an open registry for [Model Context Protocol](https://modelcontextprotocol.io) servers.
- [mpak registry](https://mpak.dev?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)
- [NimbleBrain](https://nimblebrain.ai?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)
- [MCP specification](https://modelcontextprotocol.io)
- [Discord community](https://nimblebrain.ai/discord?utm_source=github&utm_medium=readme&utm_campaign=mcp-bash)
## License
MIT
