MCP Bash

🚀 MCP Bash

A simple Model Context Protocol (MCP) server for executing bash commands. This project allows you to execute arbitrary bash commands through the MCP server interface, along with all potential security risks! Since I couldn't find anything similar publicly available when writing this, I wrote my own. It's very useful when having Claude Desktop write code (it can run tests, evaluate results, and fix issues it finds).

🚀 Quick Start

MCP Bash provides a straightforward way to execute bash commands from client applications. It wraps command execution in a controlled environment and returns the standard output and standard error of the executed commands.

✨ Features

• Execute arbitrary bash commands.
• Set and maintain the working directory across command executions.
• Provide a clean interface via the Model Context Protocol (MCP).
• Simple to deploy and easy to extend.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• pip or another 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 .
   

💻 Usage Examples

Start the server

python -m mcp.cli.server --module server

Use in conjunction with Claude Desktop configuration

To use it in conjunction with Claude Desktop, add the following to your configuration (usually located at /Users//Library/Application Support/Claude/claude_desktop_config.json, or view "Settings -> Developers" in the 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: "Use the Bash MCP tool to list the files in my current directory"

Use the API

The server exposes two main functions:

1. set_cwd(path): Set the working directory for bash commands.
2. execute_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 the 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())

🔧 Technical Details

This server directly executes bash commands, which can be a critical security risk if not restricted. LLMs have nothing to prevent running dangerous commands (such as rm -rf /). For personal use, the utility may outweigh the risks, but be cautious when deploying.

Consider:

• Running in a container or restricted environment.
• Adding command validation or an allow list.
• Limiting file system access with appropriate user permissions.

📄 License

This project is released under the MIT License - see the LICENSE file for details.

🤝 Contribution

Contributions are welcome! Feel free to submit pull requests.