OpenSandbox MCP Server

一个基于 Model Context Protocol (MCP) 的服务器，用于调用 OpenSandbox API，提供沙箱管理、命令执行和文件操作能力。

功能特性

• 沙箱管理: 创建、列出、查询和销毁沙箱实例
• 命令执行: 在沙箱内执行 Shell 命令
• 文件操作: 读取、写入、列出和删除沙箱内的文件

前置依赖

使用此 MCP Server 前需要：

1. 安装并运行 Docker
2. 启动 OpenSandbox Server（参考 OpenSandbox 文档）

注意： Execd 组件会自动启动（作为进程运行在沙箱容器内部），无需手动启动。

安装

方式一：通过 npm 安装（推荐）

npm install -g opensandbox-mcp-server

安装后，可执行文件 opensandbox-mcp-server 将全局可用。

方式二：从源码安装

# 克隆仓库
git clone https://github.com/yanxxcloud/ali-opensendbox-mcp-server.git
cd ali-opensendbox-mcp-server

# 安装依赖
npm install

# 编译
npm run build

配置

环境变量

| 变量 | 描述 | 默认值 | |------|------|--------| | OPENSANDBOX_DOMAIN | OpenSandbox API 地址 | localhost:8080 | | OPENSANDBOX_API_KEY | API 认证密钥 | - | | OPENSANDBOX_PROTOCOL | 协议 (http/https) | http |

Cursor 配置

在 ~/.cursor/mcp.json 中添加配置：

如果通过 npm 全局安装：

{
  "mcpServers": {
    "opensandbox": {
      "command": "opensandbox-mcp-server",
      "env": {
        "OPENSANDBOX_DOMAIN": "localhost:8080",
        "OPENSANDBOX_API_KEY": "your-api-key"
      }
    }
  }
}

如果从源码安装：

{
  "mcpServers": {
    "opensandbox": {
      "command": "node",
      "args": ["/path/to/ali-opensendbox-mcp-server/dist/index.js"],
      "env": {
        "OPENSANDBOX_DOMAIN": "localhost:8080",
        "OPENSANDBOX_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop 配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加配置：

如果通过 npm 全局安装：

{
  "mcpServers": {
    "opensandbox": {
      "command": "opensandbox-mcp-server",
      "env": {
        "OPENSANDBOX_DOMAIN": "localhost:8080",
        "OPENSANDBOX_API_KEY": "your-api-key"
      }
    }
  }
}

如果从源码安装：

{
  "mcpServers": {
    "opensandbox": {
      "command": "node",
      "args": ["/path/to/ali-opensendbox-mcp-server/dist/index.js"],
      "env": {
        "OPENSANDBOX_DOMAIN": "localhost:8080",
        "OPENSANDBOX_API_KEY": "your-api-key"
      }
    }
  }
}

可用工具

沙箱管理

| 工具 | 描述 | |------|------| | sandbox_create | 创建新的沙箱实例 | | sandbox_kill | 终止并删除沙箱 | | sandbox_list | 列出所有沙箱（可按状态过滤） | | sandbox_info | 获取指定沙箱的详细信息 |

命令执行

| 工具 | 描述 | |------|------| | command_run | 在沙箱内执行 Shell 命令 |

文件操作

| 工具 | 描述 | |------|------| | file_read | 读取沙箱内的文件内容 | | file_write | 写入文件到沙箱 | | file_write_batch | 批量写入多个文件 | | file_list | 列出沙箱内目录的文件 | | file_delete | 删除沙箱内的文件 |

使用示例

启动 OpenSandbox Server 后，在 Cursor 或 Claude Desktop 中可以使用以下提示：

创建一个 Ubuntu 沙箱，然后在里面执行 "echo Hello World"

列出所有正在运行的沙箱

在沙箱 xxx 中写入文件 /tmp/test.txt，内容为 "Hello OpenSandbox"

读取沙箱 xxx 中的文件 /tmp/test.txt

在沙箱 xxx 中执行命令 "ls -la /tmp"

API 实现说明

本 MCP Server 基于 OpenSandbox 的 REST API 实现：

• 沙箱管理：通过生命周期管理 API (/sandboxes)
• 命令执行：通过 execd API (/command)，使用 SSE 流式响应
• 文件操作：通过 execd API (/files/upload, /files/download, /files/search, /files)

Execd 服务运行在沙箱容器内部（作为进程，不是独立容器），通过 embedding-proxy-port 访问。

开发

# 监听模式编译
npm run dev

# 运行服务器
npm start

项目结构

ali-opensendbox-mcp-server/
├── src/
│   ├── index.ts              # 入口文件
│   ├── server.ts             # MCP Server 配置
│   ├── client/
│   │   └── opensandbox.ts    # OpenSandbox HTTP API 客户端
│   ├── tools/
│   │   ├── sandbox.ts        # 沙箱管理工具
│   │   ├── command.ts        # 命令执行工具
│   │   └── file.ts           # 文件操作工具
│   └── types/
│       └── index.ts          # TypeScript 类型定义
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
└── README.md

许可证

MIT