mcp-bash

MCP Bash exposes a simple interface to execute bash commands through the Model-Context-Protocol. It maintains a working directory across commands, so subsequent commands operate from the same directory unless you change it. You can start the server with Python and then interact with it via the MCP client to set the working directory and run arbitrary shell commands, receiving both stdout and stderr as results. This is useful for automating shell tasks from an LLM or other clients while keeping command execution encapsulated in a server.

Prerequisites

• Python 3.10 or higher
• pip (or another Python package manager)

Setup

1. Clone the repository git clone https://github.com/yourusername/mcp-bash.git cd mcp-bash

2. Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

3. Install dependencies pip install -e .

4. Run the server python -m mcp.cli.server --module server

Optional: If you plan to integrate with Claude Desktop or other tools, ensure the server is reachable at the expected URL/port (default may be http://localhost:8000).

Security: This server executes bash commands, which can be dangerous. Do not expose it publicly. Consider running in a restricted environment or container, and implement validation or allowlists for commands if possible. If you need to persist or restrict filesystem access, consider running under a restricted user and configuring working directory boundaries. When integrating with Claude Desktop, ensure the client configuration references the correct path to the server module and that the MCP server name matches the client configuration.