MCP Code Execution Mode：给 AI 编程工具装上安全沙箱

项目地址：https://github.com/elusznik/mcp-server-code-execution-mode
Stars：336 | 语言：Python | 许可证：GPL-3.0
核心定位：MCP 协议下的安全 Python 代码执行桥梁，用容器化沙箱解决 AI Agent 代码执行的 Token 开销与安全隐患。

---

一、痛点：从"工具调用"到"工具爆炸"

在 AI Agent 时代，Claude Code 这类工具需要调用大量外部工具（MCP Tools）来完成任务——文件读写、搜索、API 调用、数据库操作……当工具数量超过 100 个时，每个工具定义的 schema（参数描述、返回值格式）加起来可能高达 30,000 个 tokens，直接导致 Context 溢出或成本爆炸。

传统解决方案是精简工具描述，但这样会损失工具的能力边界和安全性。更深层的问题是：AI Agent 需要执行用户提供的任意 Python 代码，但直接在你的主机上跑陌生代码等于把门禁卡交给陌生人。

Anthropic 和 Cloudflare 先后提出了一个思路：把代码执行隔离在沙箱里，同时让工具发现不需要消耗大量 Context。mcp-server-code-execution-mode 就是这一思路的开源实现。

---

二、核心原理：零上下文发现 + 根less 容器隔离

2.1 零上下文发现（Zero-Context Discovery）

传统 MCP 工具定义是这样的：

Tool: mcp_vault_get_secret
  description: "获取密钥保管库中的密钥"
  input_schema: { type: object, properties: { key: string }, required: [key] }
  → 每个工具 300-500 tokens，100 个工具 = 30,000 tokens

mcp-server-code-execution-mode 的"零上下文发现"模式只需要 1 个工具定义：

Tool: run_python
  description: "在隔离沙箱中执行 Python 代码"
  input_schema: { type: object, properties: { code: string }, required: [code] }
  → 固定 200 tokens，节省 99.3% 的 token 消耗

AI Agent 需要某个 MCP 工具时，只需通过 run_python 在沙箱里动态调用——工具本身不需要出现在系统提示词里。

2.2 根less 容器隔离

代码执行的安全性是核心。方案经历了多轮失败迭代（详见项目 HISTORY.md）：

• 进程级隔离（失败）：RLIMIT 可以被绕过，Sandbox Escape 风险极高
• 进程内沙箱（失败）：即使禁用了 __import__，总有其他路径实现特权升级
• 容器级隔离（当前方案）：每个执行请求在一个全新的根less 容器中运行

架构流程如下：

┌─────────────────────┐
│ MCP Client (Claude) │
└─────────┬───────────┘
          │ JSON-RPC over stdio
          ▼
┌─────────────────────────────┐
│ mcp_server_code_execution  │ ← Python MCP Server（主机侧）
│   - run_python 工具定义     │
│   - MCP 服务器代理池        │
│   - 容器生命周期管理        │
└─────────┬───────────────────┘
          │ Async subprocess + JSON stdio bridge
          ▼
┌─────────────────────────────────┐
│ Rootless Container (podman/docker) │
│   - Read-only rootfs            │
│   - Tmpfs 工作目录              │
│   - 无网络访问                  │
│   - 无 Linux capabilities      │
│   - 临时 /ipc 挂载（JSON通信）  │
└─────────┬───────────────────────┘
          │
          ▼
┌──────────────────────┐
│ python:3.14-slim     │ ← 沙箱内 Python 解释器
│   - 执行用户代码      │
│   - 通过 stdio 调用   │
│     代理的 MCP 工具   │
└──────────────────────┘

容器每次请求都是全新实例，执行完毕后自动销毁，不保留任何状态。即使恶意代码试图提权，也因为 rootless 限制无法访问主机资源。

---

三、技术栈与代码架构

3.1 核心技术依赖

依赖	版本	作用
mcp	>=1.0.0	官方 MCP SDK，实现 stdio 服务端
pydantic	>=2.10.0	数据验证和序列化
anyio	>=4.0.0	跨平台异步 I/O（支持 async/await）
toon-format	>=0.9.0b1	高效序列化格式
packaging	>=23.0	版本解析

3.2 核心类设计

主文件 mcp_server_code_execution_mode.py（约 107KB）包含以下核心组件：

• SandboxInvocation：构建沙箱入口点，管理容器生命周期，负责 JSON-over-stdio 通信协议
• PersistentMCPClient：维护与外部 MCP 服务器的持久化 stdio 会话，避免每次调用都冷启动，提升性能
• 容器运行时抽象层：同时支持 podman 和 rootless docker，通过 MCP_BRIDGE_RUNTIME 环境变量切换

3.3 安全性设计

• 只读 rootfs：容器内文件系统默认只读，防止写入敏感路径
• Tmpfs 工作目录：仅 /tmp 类目录可写，且容器退出后自动清空
• 无网络访问：容器网络完全隔离
• 无 Linux Capabilities：即使容器内进程获得 root UID，也没有任何特权
• 资源限制：可配置内存（默认 512MB）、PID 数（默认 128）、CPU、超时时间

---

四、上手使用

4.1 安装依赖

# 需要容器运行时（podman 推荐）
brew install podman   # macOS
sudo apt-get install podman  # Ubuntu

# 安装 MCP Server
uvx --from git+https://github.com/elusznik/mcp-server-code-execution-mode \
  mcp-server-code-execution-mode run

4.2 注册到 Claude Code

在 ~/.config/mcp/servers/mcp-server-code-execution-mode.json 中配置：

{
  "mcpServers": {
    "mcp-server-code-execution-mode": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/elusznik/mcp-server-code-execution-mode",
        "mcp-server-code-execution-mode", "run"
      ],
      "env": {
        "MCP_BRIDGE_RUNTIME": "podman"
      }
    }
  }
}

重启 Claude Code 后，run_python 工具即可使用。

4.3 环境变量配置

变量	默认值	说明
MCP_BRIDGE_RUNTIME	auto	容器运行时（podman/docker）
MCP_BRIDGE_IMAGE	python:3.14-slim	容器镜像
MCP_BRIDGE_TIMEOUT	30	执行超时（秒）
MCP_BRIDGE_MAX_TIMEOUT	120	最大超时限制
MCP_BRIDGE_MEMORY	512m	内存限制

---

五、局限与争议

5.1 性能开销

每次代码执行都需要启动一个全新容器，冷启动时间约 2-5 秒。对于需要频繁执行短代码的场景，容器启动开销可能超过实际执行时间。项目通过 PersistentMCPClient 复用外部 MCP 连接，但沙箱容器本身无法复用。

5.2 与宿主 MCP 工具的集成复杂度

将已有的 MCP 工具代理到沙箱内部需要正确配置 JSON-over-stdio 通信协议，对于不熟悉 MCP 协议细节的用户有一定门槛。文档中有大量关于"为什么这样做"的解释，但也意味着系统本身存在一定的复杂性。

5.3 容器运行时依赖

在没有 root 权限的受限环境中（如某些 CI/CD 系统），rootless Docker/Podman 的配置可能遇到挑战。项目明确要求这两种运行时之一，不支持直接在宿主机上执行代码（这是安全设计的刻意选择）。

---

六、行业意义与趋势

mcp-server-code-execution-mode 代表了 AI Agent 基础设施的一个重要方向：安全执行 + Token 效率优化。

当前 AI 编程工具（Claude Code、Browse等）的核心矛盾是：Agent 越强大，需要的工具越多，Context 消耗越大，最终不得不做出"删减工具描述"或"限制工具数量"的妥协。该项目用"代码执行即万能工具"的思想，从根本上绕过了这个问题。

Anthropic 和 Cloudflare 先后在自己的博客/论文中阐述了类似思路，但开源社区（elusznik）率先给出了完整可用的生产级实现，且代码质量较高（有完整的测试套件、类型检查、安全评估）。

---

七、总结评价

维度	评分	说明
技术创新	★★★★☆	零上下文发现模式是突破性思路，容器隔离方案成熟可靠
工程完成度	★★★★★	文档极其详尽（ARCHITECTURE + GUIDE + HISTORY + STATUS），测试覆盖完整
安全性	★★★★★	rootless + 资源限制 + 零网络访问，安全性设计扎实
上手难度	★★★☆☆	需要理解 MCP 协议和容器概念，有一定学习曲线
实用性	★★★★☆	在 Claude Code 生态中有明确价值

一句话总结：mcp-server-code-execution-mode 通过容器化 Python 执行环境，为 AI Agent 提供了一条"安全执行任意代码 + 极致节省 Token"的技术路径，是 AI 编程工具基础设施层面的重要补充。