Python Exec Sandbox

mcp-python-exec-sandbox

为 AI Agent 提供沙箱化的 Python 执行环境。脚本在临时隔离环境中运行，并支持内联依赖（PEP 723）——不会污染主机，不会留下虚拟环境，也不会产生软件包冲突。

为什么要用？

每个编码 Agent 都已经能在主机上运行 Python。问题在于后续会发生什么：软件包不断累积，虚拟环境四处蔓延，一次不慎的 pip install 就可能破坏系统。mcp-python-exec-sandbox 可解决这些问题：

• 脚本在沙箱中执行（Linux 上使用 bubblewrap，macOS/其他平台上使用 Docker）
• 依赖以内联方式声明，并通过 uv 在临时环境中解析
• 不会触及主机的 Python、site-packages 或虚拟环境
• 每次执行都彼此隔离，且执行结束后即可丢弃

功能特性

• 沙箱化执行——基于平台的隔离机制可防止访问主机文件系统
• PEP 723 内联元数据——通过 # /// script 块直接在脚本中声明依赖
• 多版本 Python——可在 Python 3.13、3.14 或 3.15 上运行脚本（uv 会自动下载对应版本）
• 临时环境——每次执行时解析依赖，绝不持久保存
• 软件包缓存——uv 的全局缓存让重复安装几乎瞬间完成
• 超时控制——可配置每次执行的超时时间
• 输出截断——防止过量输出淹没 Agent

前置条件

所有配置均需满足：

• Python 3.13+——用于运行 MCP 服务进程
• uv——管理脚本执行、依赖解析和 Python 版本下载。还提供 uvx，可在不全局安装服务的情况下运行它。

其他要求取决于所选的沙箱后端：

配置	其他要求	安装
原生沙箱（Linux）	bubblewrap	sudo apt install bubblewrap
Docker 沙箱（macOS、任意）	Docker Engine	请参阅 Docker 文档
无沙箱	无	--

**主机 Python 与执行 Python：**二者相互独立。运行服务进程本身需要 Python 3.13+。--python-version 标志用于指定脚本运行所用的 Python 版本——uv 会自动下载目标版本。若要在这些版本上运行脚本，无需在主机上安装 Python 3.14 或 3.15。

快速开始

Claude Code（Linux——原生沙箱）

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox

Claude Code（macOS——Docker 沙箱，推荐）

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox

首次使用时，Docker 沙箱镜像会自动从 GHCR 拉取。无需手动构建。

Claude Code（无沙箱）

claude mcp add python-sandbox -- uvx mcp-python-exec-sandbox --sandbox-backend none

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uvx",
      "args": ["mcp-python-exec-sandbox"]
    }
  }
}

OpenAI Codex CLI

codex mcp add python-sandbox -- uvx mcp-python-exec-sandbox

或者添加到 .codex/config.toml：

[mcp_servers.python-sandbox]
command = "uvx"
args = ["mcp-python-exec-sandbox"]

其他 MCP 客户端

任何支持 MCP stdio 传输的客户端都可以使用此服务：

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uvx",
      "args": ["mcp-python-exec-sandbox"]
    }
  }
}

多版本 Python

使用 --python-version 指定目标 Python 版本。uv 会自动下载，无需手动安装。

# Python 3.13 (default)
uvx mcp-python-exec-sandbox --python-version 3.13

# Python 3.14
uvx mcp-python-exec-sandbox --python-version 3.14

# Python 3.15
uvx mcp-python-exec-sandbox --python-version 3.15

此功能适用于所有沙箱后端。Docker 沙箱会在容器内使用 uv 管理 Python 版本，因此同样适用 --python-version 标志。

工具

execute_python

执行 Python 脚本并自动管理依赖项。

参数	类型	默认值	描述
script	str	必填	Python 源代码，可包含 PEP 723 内联元数据
dependencies	list[str]	[]	要合并的额外 PEP 508 依赖项说明符
timeout_seconds	int	30	最长执行时间（1--300）

# Simple script
execute_python(script="print('hello world')")

# Script with dependencies
execute_python(
    script="import requests; print(requests.get('https://httpbin.org/get').status_code)",
    dependencies=["requests"]
)

# Script with inline PEP 723 metadata
execute_python(script="""
# /// script
# dependencies = ["pandas", "matplotlib"]
# ///

import pandas as pd
print(pd.DataFrame({'a': [1,2,3]}).describe())
""")

check_environment

返回执行环境信息：Python 版本、uv 版本、平台、沙盒状态和配置。

validate_script

验证脚本的 PEP 723 元数据和依赖项，但不执行脚本。

参数	类型	默认值	描述
script	str	必填	要验证的 Python 源代码
dependencies	list[str]	[]	要验证的额外依赖项说明符

沙盒后端

后端	平台	工具	备注
native	Linux	bubblewrap	命名空间隔离，允许联网
docker	任意	Docker	容器隔离，资源限制
none	任意	--	不使用沙盒（不推荐）

在 Linux 上，默认后端为 native（bubblewrap）；在 macOS/其他平台上则为 docker。在 macOS 上指定 --sandbox-backend native 会自动切换到 Docker。如果沙盒工具不可用，服务会发出警告并回退到 none。

Docker 沙盒设置

Docker 沙盒镜像发布在 GHCR 上，并会在服务启动时自动拉取。无需手动设置。

若要在本地构建以进行开发：

docker build -t ghcr.io/lu-zhengda/mcp-python-exec-sandbox profiles/

CLI 选项

mcp-python-exec-sandbox [OPTIONS]

Options:
  --python-version TEXT     Python version for execution (default: 3.13)
  --sandbox-backend TEXT    native | docker | none (default: native on Linux, docker on macOS)
  --max-timeout INT         Maximum allowed timeout in seconds (default: 300)
  --default-timeout INT     Default timeout in seconds (default: 30)
  --max-output-bytes INT    Maximum output size in bytes (default: 102400)
  --no-warm-cache           Skip cache warming on startup
  --uv-path TEXT            Path to uv binary (default: uv)

开发

设置

git clone https://github.com/lu-zhengda/mcp-python-exec-sandbox.git
cd mcp-python-exec-sandbox
uv sync --dev

项目结构

src/mcp_python_exec_sandbox/   # Package source
  server.py               # FastMCP server + tool definitions
  executor.py             # uv subprocess orchestration
  script.py               # PEP 723 metadata parsing/merging
  sandbox.py              # Sandbox ABC + factory
  sandbox_linux.py        # bubblewrap sandbox (Linux)
  sandbox_docker.py       # Docker sandbox (macOS/any)
  config.py, cache.py, output.py, errors.py
tests/                    # Unit + integration tests (mocked or local uv)
e2e_tests/                # End-to-end tests (require uv + network)
profiles/                 # Dockerfile, warmup packages
.devcontainer/            # Devcontainer for Linux sandbox testing from macOS

运行测试

单元测试和集成测试——快速，可在任何环境中运行：

uv run pytest tests/ -v

E2E 测试——需要 uv 和网络访问。这些测试会验证实际脚本执行、软件包安装、MCP 协议流程和沙盒强制执行：

uv run pytest e2e_tests/ -v

Docker 沙盒测试

Docker E2E 测试（e2e_tests/test_docker_sandbox.py）通过 Docker 后端验证执行、依赖项安装、只读文件系统强制执行、主机隔离和超时处理。

前置条件：

1. 必须安装并运行 Docker
2. 构建沙盒镜像：

docker build -t ghcr.io/lu-zhengda/mcp-python-exec-sandbox profiles/

然后运行：

uv run pytest e2e_tests/test_docker_sandbox.py -v

如果 Docker 不可用或尚未构建镜像，这些测试会自动跳过。

Linux 沙盒测试（devcontainer）

Linux 沙盒测试（e2e_tests/test_sandbox_enforcement.py::test_linux_sandbox_blocks_etc_shadow）使用 bubblewrap（bwrap）进行命名空间隔离。由于 bwrap 仅适用于 Linux，因此这些测试在 macOS 上会跳过。

要在 macOS 上运行这些测试，请使用随附的 devcontainer，其中预装了 bwrap 的 Ubuntu 24.04：

VS Code：

1. 安装 Dev Containers 扩展
2. 打开项目并选择 在容器中重新打开
3. 在集成终端中：

uv run pytest e2e_tests/test_sandbox_enforcement.py -v

命令行：

# Install the devcontainer CLI (once)
npm install -g @devcontainers/cli

# Build and start the container
devcontainer up --workspace-folder .

# Run the Linux sandbox tests inside the container
devcontainer exec --workspace-folder . uv run pytest e2e_tests/test_sandbox_enforcement.py -v

测试矩阵

测试套件	命令	要求
单元测试	uv run pytest tests/ -v	uv
集成测试	uv run pytest tests/test_integration.py -v	uv
E2E（通用）	uv run pytest e2e_tests/ -v	uv、网络
E2E（Docker 沙盒）	uv run pytest e2e_tests/test_docker_sandbox.py -v	uv、Docker、沙盒镜像
E2E（Linux/bwrap 沙盒）	uv run pytest e2e_tests/test_sandbox_enforcement.py -v	uv、安装了 bwrap 的 Linux（或 devcontainer）

贡献

• 每次提交只包含一项逻辑变更。提交消息应具有描述性，并使用祈使语气。
• 提交前运行 uv run pytest tests/ -v——所有测试都必须通过。
• 为新功能添加测试：在 tests/ 中添加单元测试；如果需要实际执行，则在 e2e_tests/ 中添加端到端测试。
• 尽量减少依赖。没有充分理由时，不要添加运行时依赖。
• server.py 中工具的文档字符串是面向用户的 MCP 工具描述。请面向大模型编写。
• 沙箱后端必须能够优雅降级：如果缺少必需工具（bwrap、docker），则回退到 NoopSandbox，并发出警告。

许可证

MIT