# Mcp Bash

> A simple model context protocol (MCP) server that allows Claude Desktop or other MCP aware clients to run Bash commands on your local machine.

- **Type:** MCP server
- **Install:** `agentstack add mcp-patrickomatik-mcp-bash`
- **Verified:** Pending review
- **Seller:** [patrickomatik](https://agentstack.voostack.com/s/patrickomatik)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [patrickomatik](https://github.com/patrickomatik)
- **Source:** https://github.com/patrickomatik/mcp-bash

## Install

```sh
agentstack add mcp-patrickomatik-mcp-bash
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
   ```bash
   git clone https://github.com/yourusername/mcp-bash.git
   cd mcp-bash
   ```

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

3. Install dependencies
   ```bash
   pip install -e .
   ```

## Usage

### Starting the server

```bash
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):

```json
{
  "mcpServers": {
    "Bash": {
      "command": "/Users//.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

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [patrickomatik](https://github.com/patrickomatik)
- **Source:** [patrickomatik/mcp-bash](https://github.com/patrickomatik/mcp-bash)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-patrickomatik-mcp-bash
- Seller: https://agentstack.voostack.com/s/patrickomatik
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.