bash-mcp

touwaeriol/bash-mcp

3.2

If you are the rightful owner of bash-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Bash MCP Server is a Model Context Protocol server designed to execute bash commands on a host machine.

Tools

  1. execute_command

    Executes a specified bash command with optional working directory and timeout.

Bash MCP Server

English | 中文

English

A Model Context Protocol (MCP) server that enables execution of bash commands on the host machine.

Features

  • Execute arbitrary bash commands
  • Configurable working directory
  • Command timeout support
  • Returns stdout, stderr, and exit code

Installation

Using pip
pip install bash-mcp
From source
git clone https://github.com/touwaeriol/bash-mcp.git
cd bash-mcp
pip install -e .

Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "bash-mcp": {
      "command": "python",
      "args": ["-m", "bash_mcp"]
    }
  }
}

Usage

The server provides an execute_command tool with the following parameters:

  • command (required): Bash command to execute
  • cwd (optional): Working directory for command execution
  • timeout (optional): Command timeout in seconds (default: 30)
Example Request
{
  "tool": "execute_command",
  "arguments": {
    "command": "ls -la",
    "cwd": "/home/user",
    "timeout": 10
  }
}
Example Response
{
  "success": true,
  "stdout": "total 24\ndrwxr-xr-x  6 user user 4096 Dec 10 10:00 .\n...",
  "stderr": "",
  "code": 0,
  "command": "ls -la",
  "executedAt": "2024-12-10T10:00:00.000Z"
}

Security Warning

⚠️ WARNING: This MCP server can execute arbitrary system commands. Use with caution:

  • Only use in trusted environments
  • Be careful with commands that could damage your system
  • Consider implementing access controls

Development

Requirements
  • Python >= 3.8
  • mcp >= 0.1.0
  • pydantic >= 2.0.0
Local Development
# Clone the repository
git clone https://github.com/touwaeriol/bash-mcp.git
cd bash-mcp

# Install in development mode
pip install -e .

# Run the server
python -m bash_mcp

License

MIT License

中文

一个用于在宿主机上执行 bash 命令的 MCP（Model Context Protocol）服务器。

功能特性

  • 执行任意 bash 命令
  • 支持指定工作目录
  • 可配置命令超时时间
  • 返回标准输出、标准错误和执行状态

安装

使用 pip
pip install bash-mcp
从源码安装
git clone https://github.com/touwaeriol/bash-mcp.git
cd bash-mcp
pip install -e .

配置

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "python",
      "args": ["-m", "bash_mcp"]
    }
  }
}

使用示例

MCP 服务器提供了一个 execute_command 工具，支持以下参数：

  • command (必需): 要执行的 bash 命令
  • cwd (可选): 工作目录
  • timeout (可选): 超时时间（秒），默认 30 秒
示例请求
{
  "tool": "execute_command",
  "arguments": {
    "command": "ls -la",
    "cwd": "/home/user",
    "timeout": 10
  }
}
示例响应
{
  "success": true,
  "stdout": "total 24\ndrwxr-xr-x  6 user user 4096 Dec 10 10:00 .\n...",
  "stderr": "",
  "code": 0,
  "command": "ls -la",
  "executedAt": "2024-12-10T10:00:00.000Z"
}

安全注意事项

⚠️ 警告: 此 MCP 服务器可以执行任意系统命令，请谨慎使用：

  • 仅在受信任的环境中使用
  • 避免执行可能造成系统损坏的命令
  • 建议配置适当的权限和访问控制

开发

依赖项
  • Python >= 3.8
  • mcp >= 0.1.0
  • pydantic >= 2.0.0
本地开发
# 克隆仓库
git clone https://github.com/touwaeriol/bash-mcp.git
cd bash-mcp

# 安装开发依赖
pip install -e .

# 运行服务器
python -m bash_mcp

许可证

MIT License