OpenSandbox MCP Server

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

功能特性

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

前置依赖

使用此 MCP Server 前需要：

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

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

安装

$3

``bash
npm install -g opensandbox-mcp-server
`

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

$3

`bash


克隆仓库

git clone https://github.com/yanxxcloud/ali-opensendbox-mcp-server.git
cd ali-opensendbox-mcp-server

安装依赖

npm install

编译

npm run build
`

配置

$3

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

$3

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

如果通过 npm 全局安装：
`json
{
"mcpServers": {
"opensandbox": {
"command": "opensandbox-mcp-server",
"env": {
"OPENSANDBOX_DOMAIN": "localhost:8080",
"OPENSANDBOX_API_KEY": "your-api-key"
}
}
}
}
`

如果从源码安装：
`json
{
"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"
}
}
}
}
`

$3

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

如果通过 npm 全局安装：
`json
{
"mcpServers": {
"opensandbox": {
"command": "opensandbox-mcp-server",
"env": {
"OPENSANDBOX_DOMAIN": "localhost:8080",
"OPENSANDBOX_API_KEY": "your-api-key"
}
}
}
}
`

如果从源码安装：
`json
{
"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"
}
}
}
}
`

可用工具

$3

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

$3

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

$3

| 工具 | 描述 |
|------|------|
| 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 访问。

开发

`bash


监听模式编译

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