MCP代码沙箱服务器

一个可扩展的消息通信协议（MCP）服务器，提供在隔离沙箱环境中安全执行代码的能力。该服务器遵循MCP标准，使其与桌面版Claude和其他MCP客户端兼容。

特性

• 创建用于代码执行的隔离沙箱环境
• 安全地执行Python代码
• 执行文件操作（列出、读取、写入）
• 在沙箱中安装Python包
• 具有抽象代码解释器接口的可扩展架构
• 模块化设计，清晰的责任分离

架构

服务器采用模块化、可扩展的架构：

核心组件

• 抽象解释器接口：允许集成不同的代码执行后端
• 沙箱管理：创建和管理沙箱环境的工具
• 代码执行：运行代码和安装包的工具
• 文件操作：管理沙箱内文件的工具

项目结构

├── src/
│   └── sandbox/
│       ├── __pycache__/
│       ├── e2b/
│       │   ├── __pycache__/
│       │   ├── __init__.py
│       │   ├── e2b_file_interface.py
│       │   └── e2b_interpreter.py
│       ├── __init__.py
│       ├── code_interpreter.py
│       ├── file_interface.py
│       └── interpreter_factory.py
├── tools/
│   ├── __pycache__/
│   ├── __init__.py
│   ├── code_execution_tools.py
│   ├── file_tools.py
│   └── sandbox_tools.py
├── main.py
├── .env
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

预备条件

• Python 3.10或更高版本
• E2B API密钥（用于默认的E2B解释器）

安装

1. 克隆此仓库：

   git clone https://github.com/yourusername/mcp-code-sandbox.git
   cd mcp-code-sandbox
   

2. 设置虚拟环境：

   # 使用 venv
   python -m venv venv
   source venv/bin/activate  # 在Windows上：venv\Scripts\activate
   
   # 或者使用 uv（推荐）
   uv init
   uv venv
   source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
   

3. 安装所需的包：

   # 使用 pip
   pip install fastmcp python-dotenv e2b-code-interpreter
   
   # 或者使用 uv
   uv add fastmcp python-dotenv e2b-code-interpreter
   

4. 配置环境变量：

   # 创建一个包含以下变量的 .env 文件
   E2B_API_KEY=your_e2b_api_key_here
   INTERPRETER_TYPE=e2b  # 默认值，可以更改为其他已实现的解释器
   

使用方法

单独运行服务器

你可以直接从命令行运行服务器：

python main.py

这将使用stdio传输启动服务器，使其与桌面版Claude兼容。

与桌面版Claude一起使用

1. 确保你已经安装了最新版本的桌面版Claude

2. 打开你的桌面版Claude配置文件：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. 添加你的代码沙箱服务器配置：

   {
     "mcpServers": {
       "code-sandbox": {
         "command": "python",
         "args": [
           "/ABSOLUTE/PATH/TO/main.py"
         ]
       }
     }
   }
   

   或者如果你使用的是 uv：

   {
     "mcpServers": {
       "code-sandbox": {
         "command": "uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/PROJECT_DIRECTORY",
           "run",
           "main.py"
         ]
       }
     }
   }
   

4. 保存文件并重启桌面版Claude

提供的工具

服务器提供了以下工具：

沙箱管理

• create_sandbox：创建新的沙箱环境
• close_sandbox：关闭并清理沙箱
• get_sandbox_status：检查沙箱状态

代码执行

• execute_code：在沙箱中运行Python代码
• install_package：安装Python包
• create_run_close：一键式工具，创建沙箱、运行代码并清理

文件操作

• list_files：列出沙箱中的文件
• read_file：读取文件内容
• write_file：向文件写入内容
• upload_file：上传文件到沙箱

扩展新解释器

系统设计为可扩展。要添加新的代码解释器：

1. 在 src/sandbox/ 下为你的解释器实现创建一个新的目录
2. 实现 src/sandbox/code_interpreter.py 和 src/sandbox/file_interface.py 中定义的接口
3. 将新的解释器类型添加到 src/sandbox/interpreter_factory.py
4. 配置环境变量 INTERPRETER_TYPE 为你的新解释器

实现新解释器的例子：

# src/sandbox/my_backend/my_interpreter.py
from src.sandbox.code_interpreter import CodeInterpreter, ExecutionResult
from src.sandbox.file_interface import FileInterface

class MyFileInterface(FileInterface):
    # 实现所需的方法
    
class MyInterpreter(CodeInterpreter):
    # 实现所需的方法

# 更新 src/sandbox/interpreter_factory.py 以包含你的新解释器

模块描述

沙箱核心 (src/sandbox/)

• code_interpreter.py：代码解释器的抽象基类
• file_interface.py：文件操作的抽象接口
• interpreter_factory.py：创建代码解释器实例的工厂

E2B实现 (src/sandbox/e2b/)

• e2b_interpreter.py：E2B代码解释器的实现
• e2b_file_interface.py：E2B文件操作的实现

工具 (tools/)

• sandbox_tools.py：沙箱管理工具
• code_execution_tools.py：代码执行工具
• file_tools.py：文件操作工具

主应用程序

• main.py：主应用程序入口点

故障排除

如果遇到问题：

• 确保你为所选解释器拥有正确的API密钥
• 查看日志获取详细的错误信息
• 验证是否安装了所有必需的包
• 确保桌面版Claude配置了正确的脚本路径

安全注意事项

• 代码执行发生在隔离的沙箱环境中，确保安全性
• 不要在生产环境中使用此服务器执行未经验证的代码
• 服务器当前不实现身份验证——仅应在受信任的环境中使用

许可证

MIT许可证