What is Mcp Bash

mcp-bash is a simple Model-Context-Protocol (MCP) server that allows clients, such as Claude Desktop, to execute Bash commands on a local machine.

Use cases

Use cases include running tests, assessing results, and fixing issues in code through integration with Claude Desktop, as well as executing system commands for automation purposes.

How to use

To use mcp-bash, clone the repository, set up a virtual environment, install dependencies, and start the server using the provided command. Configure Claude Desktop to connect to the MCP server for executing commands.

Key features

Key features include the ability to execute arbitrary Bash commands, maintain a working directory across executions, a clean interface through the Model-Context-Protocol (MCP), and ease of deployment and extension.

Where to use

mcp-bash can be used in software development environments, automation tasks, and any scenario where Bash command execution is required from a client application.

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

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