mcp4modal sandbox

MCP4模式沙箱

一个强大的模型上下文协议（MCP）服务器，使用Modal.com提供无缝的基于云的沙盒管理。该项目使LLM和AI助手能够在完全GPU支持的情况下生成、管理云中的孤立计算环境并与之交互。

特性

核心沙盒管理

• 启动沙盒：使用自定义配置创建隔离的Python环境
• 终止沙盒：清洁资源管理和受控停机
• 列出沙盒：监视和跟踪活动沙盒环境
• 应用程序命名空间：在Modal应用程序命名空间中组织沙盒

高级配置

• Python版本：支持多个Python版本（默认：3.12）
• 包管理：在创建沙盒时安装pip和apt包
• 资源分配：配置CPU内核、内存和执行超时
• 工作目录：为沙盒环境设置自定义工作目录

GPU支持

为机器学习和计算密集型工作负载提供全面的GPU支持：

• 四碘甲腺原氨酸：入门级GPU，非常适合推理工作负载
• L4：用于一般机器学习任务的中端GPU
• 10克：用于训练的高性能GPU（最多4个GPU）
• 100-40GB/80GB：用于大规模训练的高端GPU
• 1940年代：用于ML工作负载的最新一代GPU
• H100：最新一代高端GPU
• H200：最新一代旗舰GPU
• B200：最新一代企业级GPU

文件操作

• 推送文件：将文件从本地文件系统上传到沙盒
• 拉取文件：将文件从沙盒下载到本地文件系统
• 读取文件内容：直接查看文件内容，无需下载
• 写入文件内容：在沙盒中创建和编辑文件
• 目录管理：创建、列出和删除目录

命令执行

• 远程执行：在沙盒环境中运行任意命令
• 输出捕获：捕获stdout、stderr和返回代码
• 超时控制：为长时间运行的任务配置执行超时
• 性能指标：跟踪执行时间和资源使用情况

安全与环境管理

• 秘密管理：注入环境变量和机密
• 预定义的秘密：参考Modal仪表板中的现有机密
• 数据载体安装：附加持久存储卷
• 孤立的环境：沙盒实例之间完全隔离

运输选项

• 标准输入输出：直接命令行界面（默认）
• 可流式传输http：基于HTTP的通信
• SSE：服务器发送实时更新事件

先决条件

• Python 3.12+
• Modal.com帐户和API密钥
• 已配置环境变量（请参阅配置部分）

安装

使用紫外线（推荐）

# Clone the repository
git clone https://github.com/milkymap/mcp4modal_sandbox.git
cd mcp4modal_sandbox

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

使用Docker

构建Docker镜像

# Build the Docker image
docker build -t mcp4modal-sandbox f Dockerfile .

使用stdio传输运行（默认）

# Run --help to find options
docker run -it \
  -e MODAL_TOKEN_ID="your_modal_token_id" \
  -e MODAL_TOKEN_SECRET="your_modal_token_secret" \
  mcp4modal-sandbox --help

配置

环境变量

创建一个 .env 项目根目录中的文件：

# Required: Modal.com API Configuration
MODAL_TOKEN_ID="your_modal_token_id"
MODAL_TOKEN_SECRET="your_modal_token_secret"

# Optional: HTTP Transport Configuration (only needed for streamable-http/sse transports)
MCP_HOST="0.0.0.0"  # Default: 0.0.0.0
MCP_PORT=8000       # Default: 8000

Modal.com设置

1. 在以下网址创建帐户 Modal.com
2. 从您的模态仪表板生成API令牌
3. 在环境变量中配置令牌

与Claude Desktop集成

添加到您的Claude Desktop配置中：

uvx

{
  "mcpServers": {
    "mcp4modal-sandbox": {
        "command": "uvx",
        "args": [
          "mcp4modal-sandbox",
          "--transport", "stdio",
          "--app_name", "namespace",
          "--preloaded_secrets", "group0", // modal secret
          "--preloaded_secrets", "group1" // modal secret
          ],
        "env": {
          "MODAL_TOKEN_ID": "",
          "MODAL_TOKEN_SECRET": ""
        }
    }
  }
}

码头工人

{
  "mcpServers": {
    "mcp4modal-sandbox": {
        "command": "docker",
        "args": [
          "run", "--rm", "-i", "--name", "modal_sandbox",
          "-e", "MODAL_TOKEN_ID", "-e", "MODAL_TOKEN_SECRET", 
          "-v", "/path/to/volume", 
          "milkymap/modal_sandbox:0.1", 
          "--transport", "stdio",
          "--app_name", "namespace",
          "--preloaded_secrets", "group0",
          "--preloaded_secrets", "group1"
          ],
        "env": {
          "MODAL_TOKEN_ID": "",
          "MODAL_TOKEN_SECRET": ""
        }
    }
  }
}

可用工具

MCP服务器提供11个全面的沙盒管理工具：

1. launch_sandbox -使用自定义配置（Python版本、软件包、GPU、secrets）创建新的Modal沙盒
2. terminate_sandbox -停止并清理正在运行的沙盒
3. list_sandboxes -列出应用命名空间中的所有沙盒及其状态
4. execute_command -在沙盒中运行shell命令并捕获输出
5. push_file_to_sandbox -将文件从本地文件系统上传到沙盒
6. pull_file_from_sandbox -将文件从沙盒下载到本地文件系统
7. list_directory_contents -列出沙盒中目录的内容
8. make_directory -在沙盒中创建目录
9. remove_path -从沙盒中删除文件或目录
10. read_file_content_from_sandbox -直接从沙盒读取文件内容
11. write_file_content_to_sandbox -将内容写入沙盒中的文件