Skip to main content
Glama
NimbleBrainInc

Bash MCP Server

by NimbleBrainInc
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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 NimbleBrain

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.

Related MCP server: MCP Terminal Tool Server

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:

  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 and built by NimbleBrain. mpak is an open registry for Model Context Protocol servers.

License

MIT

Available Tools

1 tool
bash_execA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesThe bash command to execute
cwdNoWorking directory (defaults to server's cwd)
timeoutNoTimeout in seconds (default 30, max 600)
envNoAdditional environment variables to set

Output Schema

ParametersJSON Schema
NameRequiredDescription
stdoutYesCommand standard output
stderrYesCommand standard error
exit_codeYesExit code (124 = timeout)
duration_msYesExecution time in milliseconds

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the return values (stdout, stderr, exit code, duration), which is helpful. However, it omits behavioral details like side effects, error handling, permissions, or security implications, which are essential for a bash execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the action and returns concise, relevant information. Every word serves a purpose with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the output schema covers return values and the schema covers parameters, the description is minimally adequate. However, it lacks critical context about safety, side effects, and usage boundaries, which are important for a potentially dangerous tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning about the parameters beyond what the schema already provides; it merely restates the action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'execute' and the resource 'bash command', and lists the return values (stdout, stderr, exit code, duration). It is specific and leaves no ambiguity about the tool's purpose, even without sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it specify any prerequisites or exclusions. For a command execution tool, usage context is critical but absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool update
    • Changedbash_exec4 fields changed
      • addedInput schema / properties / command / description
        Added value: +"The bash command to execute"
      • addedInput schema / properties / cwd / description
        Added value: +"Working directory (defaults to server's cwd)"
      • addedInput schema / properties / env / description
        Added value: +"Additional environment variables to set"
      • addedInput schema / properties / timeout / description
        Added value: +"Timeout in seconds (default 30, max 600)"
  2. 1 tool updatev0.1.0
    • First observedbash_exec
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of confusion between tools. The tool's purpose is uniquely defined.

Naming Consistency5/5

The single tool name 'bash_exec' follows a clear verb_noun pattern, which is consistent and descriptive.

Tool Count3/5

With only one tool, the server feels minimal for a bash execution service. While it covers the core operation, the count is at the borderline of being too thin.

Completeness3/5

The tool provides basic execution with stdout/stderr/exit code/duration, but lacks features like timeout control, environment variable setting, or working directory specification, leaving notable gaps.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Terminal Tool Server

    gkgaurav31
    F
    license
    B
    quality
    D
    maintenance
    An MCP server that enables users to execute arbitrary shell commands on their local machine and receive the output. It provides a terminal tool for running system commands through MCP-compatible clients using the Python SDK.
    1
    -

  • mcp-bash

    patrickomatik
    A
    license
    A
    quality
    C
    maintenance
    Enables execution of bash commands via MCP, allowing clients to run shell commands and set a working directory.
    2
    33
    MIT

  • async-bash-mcp

    xhuw
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for spawning and managing bash commands asynchronously. Run multiple shell commands in parallel and check their progress independently.
    6
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NimbleBrainInc/mcp-bash'

If you have feedback or need assistance with the MCP directory API, please join our Discord server