MCP Bash
A simple Model-Context-Protocol (MCP) server for executing bash commands. This project allows you to execute bash commands via an MCP server interface, with all the potential security risks that entails! I couldn't find anything else like this in the public domain at the time of writing, so I wrote my own. It's a boon when getting Claude Desktop to write code (it can run the tests, assess the results and fix the issues is finds in one pass.)
Description
MCP Bash provides a simple way to execute bash commands from client applications. It wraps command execution in a controlled environment and returns both stdout and stderr from the executed commands.
Key features:
- Execute arbitrary bash commands
- Set and maintain a working directory across command executions
- Clean interface through the Model-Context-Protocol (MCP)
- Simple to deploy and extend
Installation
Prerequisites
- Python 3.10 or higher
- pip or another package manager
Setup
-
Clone the repository
git clone https://github.com/yourusername/mcp-bash.git cd mcp-bash
-
Create and activate a virtual environment
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
-
Install dependencies
pip install -e .
Usage
Starting the server
python -m mcp.cli.server --module server
Claude Desktop Configuration
To use this with Claude Desktop, add this to your configuration (usually /Users//Library/Application Support/Claude/claude_desktop_config.json, or see 'Settings -> Developer' in Claude Desktop UI):
{
"mcpServers": {
"Bash": {
"command": "/Users/<username>/.local/bin/uv",
"args": [
"run",
"--with",
"mcp[cli]",
"mcp",
"run",
"/path/to/server.py"
]
}
}
}
Then ask Claude: "List the files in my current directory using the Bash MCP tool"
Using the API
The server exposes two main functions:
set_cwd(path): Set the working directory for bash commandsexecute_bash(cmd): Execute a bash command and return stdout/stderr
Example client code
from mcp.client import MCPClient
async def main():
# Connect to the MCP server
client = MCPClient("http://localhost:8000")
# Set working directory
await client.set_cwd("/path/to/your/directory")
# Execute a command
stdout, stderr = await client.execute_bash("ls -la")
print(f"Command output: {stdout}")
if stderr:
print(f"Error output: {stderr}")
if __name__ == "__main__":
import asyncio
asyncio.run(main())
Security Considerations
This server executes bash commands directly, which can be a lethal security risk if not properly restricted. There's nothing stopping the LLM from running dangerous commands like rm -rf /. For personal use, the usefulness may outweigh the risks, but take care when deploying.
Consider:
- Running in a container or restricted environment
- Adding command validation or allowlists
- Limiting filesystem access with appropriate user permissions
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Metadata
Release files for iflow-mcp_patrickomatik-mcp-bash-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_patrickomatik_mcp_bash_server-0.1.0.tar.gz | 4.2 kB | Without provenance | Details for iflow_mcp_patrickomatik_mcp_bash_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_patrickomatik_mcp_bash_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_patrickomatik_mcp_bash_server-0.1.0-py3-none-any.whl |
Total release size: 9.1 kB
Release files / iflow_mcp_patrickomatik_mcp_bash_server-0.1.0.tar.gz
| Download URL | iflow_mcp_patrickomatik_mcp_bash_server-0.1.0.tar.gz |
|---|---|
| Size | 4.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fd9403a5f8ce66832798b5dfbd1d172554c543acd0bbcbd5f2430ef40564e83f
|
|
BLAKE2b-256 checksum How to use checksums |
747b785a3875053b7837e1194c7af4f7188052b53499821e08fc0d34bd359a4d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_patrickomatik_mcp_bash_server-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_patrickomatik_mcp_bash_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 4.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
13b260fd619444de580f44824df47270669224a0e8166742b85cc16c9e636737
|
|
BLAKE2b-256 checksum How to use checksums |
d2443a2b41b99af7be7f8dd5ce2fa4e7d515faaa2ba2498d187699bd6be4f065
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_patrickomatik-mcp-bash-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.