Python Code Sandbox MCP

🚀 Python代码沙箱MCP服务器

Python代码沙箱MCP服务器实现了模型上下文协议（MCP），可在临时Docker容器中运行任意Python代码，并能即时安装pip依赖项。

✨ 主要特性

• 文件持久化（智能默认设置）：默认情况下，文件会自动持久化到主机文件系统。
• 隔离执行：在临时Docker容器（默认使用 python:3.11-slim）中运行Python代码。
• 一次性执行：在一次性容器中运行脚本并立即获取结果。
• 基于会话的执行：为复杂的多步骤任务保持容器运行。
• 依赖管理：自动从PyPI安装pip包。
• 安全至上：对容器内的CPU和内存进行限制，并以非root用户身份执行。
• 文件检索：自动捕获生成的图像（绘图）和文件。

📦 安装指南

前提条件

你的机器上必须安装并运行Docker。

💡 使用建议

预拉取基础镜像以避免首次执行时的延迟：

docker pull python:3.11-slim

开始使用

与Claude桌面版配合使用

将以下内容添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "python-sandbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-e", "SANDBOX_MEMORY_LIMIT=1g",
        "-e", "SANDBOX_CPU_LIMIT=0.5",
        "aixiaoke/python-code-sandbox-mcp"
      ]
    }
  }
}

手动执行（Docker）

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SANDBOX_MEMORY_LIMIT=1g \
  aixiaoke/python-code-sandbox-mcp stdio

本地开发（不使用Docker打包）

如果你想直接从源代码运行服务器（用于开发或调试）：

前提条件：

• Python 3.10+
• uv 包管理器（安装方式：curl -LsSf https://astral.sh/uv/install.sh | sh 或 pip install uv）
• Docker（运行沙箱容器仍需要）

⚠️ 重要提示

Windows用户建议使用带有WSL2后端的Docker Desktop。确保在Docker设置中启用“使用基于WSL 2的引擎”。

步骤：

# 1. 克隆仓库
git clone https://github.com/li-xiu-qi/python-code-sandbox-mcp.git
cd python-code-sandbox-mcp

# 2. 安装依赖
uv sync --extra dev

# 3. 运行服务器
uv run python -m python_code_sandbox_mcp.server

对于Claude桌面版的本地开发：

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/python-code-sandbox-mcp",
        "python-code-sandbox"
      ]
    }
  }
}

📚 详细文档

配置

服务器支持通过环境变量或 .env 文件进行配置。主要选项包括：

文件持久化（新增）

默认情况下，沙箱中创建的文件会持久化到主机文件系统：

• Windows：%TEMP%/python-sandbox-mcp/files/
• macOS/Linux：/tmp/python-sandbox-mcp/files/

你可以自定义此行为：

• SANDBOX_FILES_DIR：设置自定义的文件持久化目录（例如 /home/user/my-sandbox-files）
• SANDBOX_FILES_DIR=""：设置为空字符串以禁用持久化（文件仅存在于容器中）

其他选项

• PIP_CACHE_PATH：（推荐）主机上用于持久化pip缓存的绝对路径。
• SANDBOX_MEMORY_LIMIT：每个容器的最大内存（默认值：2g）。
• SANDBOX_CPU_LIMIT：每个容器的CPU限制（默认值：0.5）。
• ENABLE_PIP_CACHE：设置为 false 以禁用缓存。

完整的变量列表请参阅 使用指南。

工具

run_python_ephemeral（推荐）

在全新的一次性容器中运行一次性Python脚本。

输入：

• code（字符串，必需）：要执行的Python源代码。
• dependencies（字符串数组，可选）：要安装的pip包（例如 ["pandas", "matplotlib"]）。

行为：

1. 创建一个新容器。
2. 安装指定的依赖项。
3. 执行脚本并捕获标准输出和标准错误。
4. 返回生成的文件（图像作为 image，其他文件作为 resource）。
5. 自动销毁容器。

sandbox_initialize / run_python

启动一个持久化沙箱，并在同一环境中运行多个脚本。

测试提示

连接成功后，尝试以下提示进行验证：

1. Hello World：Create and run a Python script with print("Hello MCP")
2. 数据可视化：Install matplotlib and create a sine wave plot saved as 'sine.png'

文档资源

• 使用指南 - 安装、配置和使用说明
• API参考 - 完整工具文档
• 执行模式 - 临时模式与会话模式详解
• 示例 - 使用MCP客户端的实用代码示例
• 持久化 - 文件持久化和存储选项
• 架构 - 系统设计
• 安全 - 安全指南
• 故障排除 - 常见问题及解决方案

中文文档

• 使用指南 - 安装、配置和使用说明
• API参考 - 完整工具文档
• 执行模式 - 临时模式与会话模式详解
• 使用示例 - 实用代码示例

📄 许可证

本项目采用MIT许可证。