项目简介

该项目是一个基于 Model Context Protocol (MCP) 的服务器实现，专门用于提供一个安全的 Python 代码执行环境。它允许客户端（通常是大型语言模型应用）通过标准化的 MCP 接口调用 Python 代码执行功能，并在隔离的沙箱环境中运行代码，捕获输出（包括文本和图表），并返回执行结果或错误信息。

主要功能点

Python 代码安全沙箱执行: 利用 Snekbox Docker 容器提供隔离且受限的执行环境。
支持标准输出捕获: 捕获并返回 Python 脚本的标准输出内容。
Matplotlib 图表支持: 能够处理 Matplotlib 等库生成的图表，并将其保存为 PNG 图像返回。
基于 MCP 协议: 通过标准的 Model Context Protocol (MCP) 与客户端进行通信。
Server-Sent Events (SSE) 传输: 使用 SSE 作为数据传输协议，支持实时通信。
详细执行结果与错误报告: 提供代码执行状态、返回码、文本输出、图表路径以及具体的错误信息。

安装步骤

克隆仓库: 使用 Git 克隆本仓库代码到本地：

git clone https://github.com/cloudywu0410/python_sandbox_mcp_server.git
cd python_sandbox_mcp_server

安装 Python 依赖: 确保你安装了 Python 环境（推荐使用 Python 3.8+）。使用 'uv' 或 'pip' 安装 'requirements.txt' 文件中列出的依赖项：

uv add -r requirements.txt
# 或者使用 pip:
# pip install -r requirements.txt

安装并启动 Snekbox Docker 容器: 本项目依赖 Snekbox 作为底层的 Python 沙箱环境。你需要先安装 Docker，然后拉取并启动 Snekbox 容器：

# 拉取 Snekbox 镜像
docker pull ghcr.io/python-discord/snekbox:latest

# 启动 Snekbox 容器，并映射端口
docker run -d --ipc=none --privileged -p 8060:8060 ghcr.io/python-discord/snekbox

确保容器成功启动并在 'http://localhost:8060' 监听。

(可选) 安装额外 Python 包到沙箱: 如果你的应用场景需要在沙箱中执行的代码依赖某些特定的 Python 库（如 'pandas', 'numpy' 等，除了 Matplotlib 已默认包含），你需要手动将这些库安装到 Snekbox 容器内部的用户站点目录。首先找到运行中的 Snekbox 容器 ID ('docker ps')，然后执行安装命令：
```
docker exec <容器ID> /bin/sh -c \
    'PYTHONUSERBASE=/snekbox/user_base /snekbox/python/default/bin/python -m pip install --user <package_name>'
```
将 '<容器ID>' 替换为你的 Snekbox 容器 ID，'<package_name>' 替换为你要安装的库名称。

服务器配置 (供 MCP 客户端使用)

这是一个 MCP 服务器，主要供支持 MCP 协议的客户端（如某些 LLM 集成工具、IDE 插件或其他 MCP 客户端应用）使用。客户端需要知道如何启动该服务器进程以及连接到它的信息。

根据本项目代码，服务器是一个使用 uvicorn 运行的 HTTP 服务，提供基于 SSE 的 MCP 连接。客户端通常通过配置来自动启动服务器进程并与其建立连接。

以下是一个供客户端参考的典型 MCP 服务器配置片段（通常位于客户端的配置文件中，例如 'mcp_config.json'）：

{
  "mcpServers": {
    "python-sandbox-sse": {
      // 客户端用于识别此服务器的名称，应与服务器端配置的名称一致 (默认为 "python-sandbox-mcp-sse")
      "name": "python-sandbox-sse",
      // 启动 MCP 服务器进程的命令。这里使用 uvicorn 直接运行 Starlette 应用。
      // 请确保客户端运行的环境能够找到 uvicorn 命令，并且 Python 环境已激活，依赖已安装。
      "command": "uvicorn",
      // 传递给 command 的参数。指定应用入口 (python_mcp_server:starlette_app) 和监听地址/端口。
      "args": [
        "python_mcp_server:starlette_app",
        "--host", "127.0.0.1", // 服务器实际绑定的主机地址。请根据实际部署环境修改。
        "--port", "18080" // 服务器实际监听的端口。请根据实际部署环境修改。
      ],
      // 连接类型为 SSE (Server-Sent Events)
      "type": "sse",
      // 客户端连接 SSE 流的 HTTP 路径。与服务器端代码定义的路径一致。
      "ssePath": "/sse",
      // 客户端通过 HTTP POST 发送请求的路径。与服务器端代码定义的路径一致。
      "messagePath": "/messages/"

      // 注意：README 中提到了使用 mcp-proxy 的配置方式，
      // 如果你的客户端或部署方式需要通过 mcp-proxy 转发，
      // 那么 command 和 args 会不同，mcp-proxy 会连接到此 uvicorn 启动的 HTTP 地址。
      // 示例 (如果服务器运行在 http://127.0.0.1:18080):
      // "command": "mcp-proxy",
      // "args": ["http://127.0.0.1:18080"],
      // "type": "stdio" // 客户端与 mcp-proxy 通常通过 Stdio 通信
      // 其他如 ssePath, messagePath 仍需要，因为 mcp-proxy 需要知道如何与后端服务器通信
    }
  }
}

请根据你的具体使用场景（直接启动 vs 通过 mcp-proxy）和部署环境（主机地址、端口）调整客户端配置中的 'command', 'args', 'host', 'port' 等参数。

基本使用方法

按照上述步骤完成 Python 依赖和 Snekbox Docker 容器的安装和启动。
通过上述客户端配置，配置支持 MCP 协议的 LLM 客户端。
启动 MCP 客户端。客户端通常会根据配置自动启动 'python_mcp_server' 进程（通过运行 'uvicorn' 命令）。
确认客户端成功连接到服务器，并识别到名为 'python-sandbox-sse' 的服务器及其提供的 'execute_python_code' 工具。
通过客户端界面或 API 调用 'execute_python_code' 工具，并将你想要执行的 Python 代码作为参数传入。
服务器将在 Snekbox 沙箱中执行代码，并将执行结果（文本输出、图表数据或错误信息）通过 MCP 协议返回给客户端。图表数据可能会以 base64 编码的形式返回，客户端需要负责解码和显示。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供 MCP 客户端使用)

基本使用方法

信息