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許可證。