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