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

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

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/<username>/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:

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 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.