MCP Bash

🚀 MCP Bash

MCP Bash 是一个简单的模型上下文协议（MCP）服务器，可用于执行 bash 命令。该项目允许用户通过 MCP 服务器接口执行任意 bash 命令，但这也伴随着所有潜在的安全风险。由于在开发时未找到公开可用的类似工具，所以开发者编写了这个项目。它在配合 Claude Desktop 编写代码时非常实用，Claude Desktop 可以借助它运行测试、评估结果并修复发现的问题。

🚀 快速开始

MCP Bash 提供了一种简单的方式，让客户端应用程序能够执行 bash 命令。它将命令执行封装在一个受控环境中，并返回所执行命令的标准输出和标准错误。

✨ 主要特性

• 可执行任意 bash 命令。
• 能够设置并保持跨命令执行的工作目录。
• 通过模型上下文协议（MCP）提供简洁的接口。
• 部署简单，且易于扩展。

📦 安装指南

先决条件

• Python 3.10 或更高版本。
• pip 或其他包管理器。

设置

1. 克隆仓库

git clone https://github.com/yourusername/mcp-bash.git
cd mcp-bash

2. 创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

3. 安装依赖项

pip install -e .

💻 使用示例

启动服务器

python -m mcp.cli.server --module server

与 Claude Desktop 配置结合使用

要在与 Claude Desktop 结合使用时，将以下内容添加到您的配置中（通常位于 /Users//Library/Application Support/Claude/claude_desktop_config.json，或在 Claude Desktop UI 中查看“设置 -> 开发人员”）：

{
  "mcpServers": {
    "Bash": {
      "command": "/Users/<username>/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/path/to/server.py"
      ]
    }
  }
}

然后要求 Claude：“使用 Bash MCP 工具列出我的当前目录中的文件”

使用 API

服务器公开了两个主要功能：

1. set_cwd(path)：设置 bash 命令的工作目录。
2. execute_bash(cmd)：执行 bash 命令并返回 stdout/stderr。

基础用法

from mcp.client import MCPClient

async def main():
    # 连接到 MCP 服务器
    client = MCPClient("http://localhost:8000")
    
    # 设置工作目录
    await client.set_cwd("/path/to/your/directory")
    
    # 执行命令
    stdout, stderr = await client.execute_bash("ls -la")
    
    print(f"命令输出：{stdout}")
    if stderr:
        print(f"错误输出：{stderr}")

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

⚠️ 安全注意事项

此服务器直接执行 bash 命令，若不加以限制，可能会带来严重的安全风险。大语言模型（LLM）无法阻止运行危险命令（如 rm -rf /）。对于个人使用，其实用性可能超过风险，但在部署时请务必谨慎。

考虑以下建议：

• 在容器或受限环境中运行。
• 添加命令验证或允许列表。
• 使用适当的用户权限限制文件系统访问。

📄 许可证

该项目在 MIT 许可证下发布 - 有关详细信息，请参阅 LICENSE 文件。

👥 贡献

欢迎贡献！请随意提交拉取请求。