Skip to main content
Glama

Smart Bash MCP

Tests Buy Me a Coffee

Smart Bash is a small MCP server that runs shell commands and summarizes long output, so less text is sent back to your AI assistant. It works with Claude Code, GitHub Copilot CLI and desktop app, and other stdio-compatible MCP clients.

Prerequisites

  • Python 3.10 or later and pip

  • Claude Code, GitHub Copilot CLI or desktop app, or another MCP client

  • Optionally, llama.cpp for local summaries

Short output and return_raw=True work without a language model.

Related MCP server: Shell Server

Install

From the project directory:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Optional: run a local model

On macOS with Homebrew:

brew install llama.cpp
llama-server -hf Qwen/Qwen2.5-Coder-7B-Instruct-GGUF:Q4_K_M \
  --host 127.0.0.1 --port 9931 -c 8192

On first run, llama.cpp downloads the quantized Qwen2.5-Coder 7B model. Keep the server running while using Smart Bash. Other llama.cpp installation options are in its README.

Connect your MCP client

Use absolute paths to the Python executable and server.py.

Claude Code — run this from the project directory:

claude mcp add smart-bash --scope user \
  -e LOCAL_LLM_URL=http://127.0.0.1:9931/v1/chat/completions \
  -e LOCAL_LLM_MODEL=qwen-local \
  -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

GitHub Copilot CLI and desktop app — both use the same MCP configuration. Add this entry to ~/.copilot/mcp-config.json, replacing /absolute/path/to/smart-bash with the project directory:

{
  "mcpServers": {
    "smart-bash": {
      "type": "local",
      "tools": ["*"],
      "command": "/absolute/path/to/smart-bash/.venv/bin/python",
      "args": ["/absolute/path/to/smart-bash/server.py"],
      "env": {
        "LOCAL_LLM_URL": "http://127.0.0.1:9931/v1/chat/completions",
        "LOCAL_LLM_MODEL": "qwen-local"
      }
    }
  }
}

Reconnect the server in your MCP client. You can omit the model settings if you only need short output or raw mode.

Use it

Ask your assistant to run a shell command with execute_local_bash. By default, output shorter than 300 characters is returned as-is; longer output is summarized. If the model is unavailable, Smart Bash returns a labeled fallback with up to 1,000 characters of the original output.

Use return_raw=True when you need the original command output rather than a summary—for example, for diffs, JSON, or tables. It skips the model, but still combines stdout and stderr, trims surrounding whitespace, and adds a marker, so it is not byte-for-byte output.

The tool also accepts cwd to choose a working directory and timeout in milliseconds (default 120,000; maximum 600,000).

Safety and privacy

Smart Bash runs commands with your user permissions; it is not a sandbox. Review commands and use your MCP client's approval controls. For long-output summaries, the command and up to 8,000 characters of output are sent to the configured model endpoint. Use a local model if you don't want that data sent to a remote service.

Monitoring

The optional dashboard shows rough token and context-window savings estimates, not actual model token counts or agent context usage. See MONITORING.md for local Docker or Podman setup.

Contributing

More stats and improvements are planned. Share your findings or suggestions in GitHub issues or pull requests.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables safe execution of terminal commands across different shells (bash, cmd, PowerShell) with configurable timeouts, working directories, and resource limits for command-line operations through AI assistants.
      -
    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables users to execute arbitrary shell commands through a terminal tool. It supports custom working directories, configurable execution timeouts, and safe command parsing using shlex.
      1
      -
    • F
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that exposes a tool to execute shell commands on the host machine, with customizable working directory and timeout.
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables secure execution of whitelisted shell commands through MCP, with support for stdin input, timeout control, and comprehensive output including stdout, stderr, and execution time.
      1
      MIT