bailian-sandbox-mcp
README.md
# bailian-sandbox-mcp
> MCP server for **Alibaba Cloud Bailian (Model Studio) Agent Sandbox** — give any MCP-capable agent an isolated cloud sandbox to run code, execute shell commands and read/write files.
[](https://www.npmjs.com/package/bailian-sandbox-mcp)
[](https://github.com/adorablelovelymia/bailian-sandbox-mcp/actions/workflows/ci.yml)
[](./LICENSE)
阿里云百炼 **Agent Sandbox** 的 MCP 服务器。把百炼沙箱(云端隔离的运行环境)封装成一组 MCP 工具,任何支持 MCP 的 Agent(Claude Desktop、Cursor、Cline、Cherry Studio、通义千问 Agent、自研 Agent……)都能直接创建沙箱、执行命令与代码、读写文件。
---
## 它解决什么问题
百炼 Agent Sandbox 提供的是**云端隔离沙箱**:每个实例有独立的 CPU/内存、文件系统和网络,可以跑 Python / Node 代码、执行 shell 命令、做数据分析,最长可存活 7 天,并支持暂停 / 恢复。官方接入方式是 E2B SDK 或兼容 E2B 的 REST API(见[文档](https://help.aliyun.com/zh/model-studio/sandbox-introduction))。
但 E2B 协议对 MCP 客户端并不友好:
| 痛点 | 本项目的处理 |
| --- | --- |
| E2B SDK 要求 `api_key` 形如 `e2b_<hex>`,而真实鉴权走 `Authorization: Bearer <百炼 API Key>` | 自动用阿里云 UID 生成占位 `api_key`,真实鉴权放在 header 里 |
| 模版管理(创建/查询/删除)不走 E2B SDK,只能裸调管控面 REST | 内置 `BailianControlClient`,用 `fetch` 直连管控面 |
| 每次操作都要传 sandboxID,Agent 很容易丢上下文 | 进程内维护「当前沙箱」,后续工具调用可省略 `sandbox_id` |
| 沙箱暂停 / 超时后连接会失效 | 自动识别 stale 连接并重连一次 |
| 输出可能暴涨撑爆上下文 | 所有输出统一截断,`max_output_chars` 可控 |
## 快速开始
### 1. 准备百炼沙箱
1. 开通[阿里云百炼](https://bailian.console.aliyun.com/),进入 **Sandbox**,完成一次 SLR 服务授权。
2. 在「我的模版」创建模版(镜像三选一:`code-interpreter-v1` / `browser` / `all-in-one`),记下 **templateCode**。
3. 在 Sandbox 页左下角生成 **API Key**(`sk-...`)。
4. 记下控制台右上角的 **工作空间 ID**(形如 `llm-xxxxxxxx`)与账号 **UID**。
### 2. 配置 MCP 客户端
```bash
npx -y bailian-sandbox-mcp
```
大多数客户端的配置格式如下(以 Claude Desktop / Cursor / Cline 为例):
```json
{
"mcpServers": {
"bailian-sandbox": {
"command": "npx",
"args": ["-y", "bailian-sandbox-mcp"],
"env": {
"BAILIAN_API_KEY": "sk-xxxxxxxxxxxxxxxx",
"BAILIAN_WORKSPACE_ID": "llm-xxxxxxxx",
"BAILIAN_SANDBOX_TEMPLATE": "your-template-code",
"ALIYUN_UID": "1234567890123456"
}
}
}
}
```
### 3. 环境变量
| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `BAILIAN_API_KEY` | ✅ | 百炼 API Key,`sk-` 开头。也接受 `DASHSCOPE_API_KEY` |
| `BAILIAN_WORKSPACE_ID` | ✅ | 工作空间 ID,形如 `llm-xxxxxxxx`。也接受 `DASHSCOPE_WORKSPACE_ID` |
| `BAILIAN_SANDBOX_TEMPLATE` | ➖ | 默认 templateCode,`sandbox_create` 省略参数时使用 |
| `ALIYUN_UID` | ➖ | 阿里云账号 UID,用于生成 E2B 占位 `api_key`(不填则用全 0 占位符,同样可用) |
| `BAILIAN_REGION` | ➖ | 地域,默认 `cn-beijing`(当前百炼沙箱仅支持该地域) |
| `BAILIAN_SANDBOX_URL` | ➖ | 覆盖沙箱接入地址;可填完整 URL 或裸域名 |
| `BAILIAN_EXTRA_HEADERS` | ➖ | 额外请求头,JSON(`{"x-a":"1"}`)或 `k:v,k:v` 形式 |
## 工具一览
| 工具 | 作用域 | 说明 |
| --- | --- | --- |
| `sandbox_template_list` | 管控面 | 列出工作空间内的沙箱模版 |
| `sandbox_template_info` | 管控面 | 查询单个模版(含构建状态/版本) |
| `sandbox_template_create` | 管控面 | 创建模版(镜像、规格、生命周期、环境变量、网络策略) |
| `sandbox_template_delete` | 管控面 | 删除模版(存在实例时会被拒绝) |
| `sandbox_create` | 生命周期 | 创建沙箱并设为当前沙箱 |
| `sandbox_connect` | 生命周期 | 连接已有沙箱(暂停的会从快照恢复) |
| `sandbox_info` | 生命周期 | 查询沙箱元数据(启动时间、到期时间等) |
| `sandbox_list` | 生命周期 | 列出本进程已知沙箱 + 工作空间远端沙箱 |
| `sandbox_pause` | 生命周期 | 暂停沙箱,保留文件系统 / 内存快照 |
| `sandbox_kill` | 生命周期 | **销毁**沙箱并回收资源(不可恢复) |
| `sandbox_run_command` | 执行 | 执行 shell 命令,返回退出码 / stdout / stderr |
| `sandbox_run_code` | 执行 | 执行 Python 代码(写入临时文件后运行,规避引号转义问题) |
| `sandbox_write_file` | 文件 | 写入 / 覆盖文件 |
| `sandbox_read_file` | 文件 | 读取文本文件 |
| `sandbox_list_files` | 文件 | 列出目录内容(名称/类型/大小/修改时间) |
| `sandbox_make_dir` | 文件 | 创建目录 |
| `sandbox_delete_file` | 文件 | 删除文件或目录 |
所有工具都带 MCP annotations(`readOnlyHint` / `destructiveHint` / `idempotentHint`),便于客户端做权限提示。
## 典型用法
> **用户**:把这份 CSV 做个透视表,画张图,然后把结果文件列出来。
Agent 的调用序列大致是:
```
sandbox_create({ template: "tpl-xxxx" }) → sbx-abc123
sandbox_write_file({ path: "/home/user/workspace/data.csv", content: "..." })
sandbox_run_code({ code: "import pandas as pd; ..." })
sandbox_list_files({ path: "/home/user/workspace" })
sandbox_kill({}) → 释放资源
```
后续调用可以完全省略 `sandbox_id`,服务器会自动使用最近创建 / 连接的沙箱。
## 实现要点
```
src/
config.ts 环境变量 → 配置(含 URL 推导、header 解析)
control.ts 百炼管控面 REST 客户端:模版管理 / 文件上传 / 沙箱列表
e2b.ts E2B 连接参数封装(Bearer 鉴权 + e2b_ 占位 key)
registry.ts 当前沙箱缓存 + stale 连接自动重连
tools.ts 17 个 MCP 工具注册
server.ts McpServer 装配 + stdio 启动
index.ts CLI 入口(--help)
```
**鉴权方式**(与[官方文档](https://help.aliyun.com/zh/model-studio/sandbox-sdk)一致):
```ts
Sandbox.create({
apiUrl: "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sandbox",
apiKey: `e2b_${ALIYUN_UID}`, // 仅用于满足 SDK 格式校验
apiHeaders: { Authorization: `Bearer ${API_KEY}` }, // 真正的鉴权
template: "your-template-code",
});
```
## 计费与安全提示
- 沙箱按运行时长与规格计费,**用完请调用 `sandbox_kill`**;`sandbox_pause` 只保留快照不销毁实例。
- API Key 只通过环境变量传入,不会出现在工具参数或返回结果中;错误信息会携带 `request_id` 便于排查。
- `sandbox_kill`、`sandbox_delete_file`、`sandbox_template_delete` 标记为 destructive,请在客户端侧确认交互策略。
## 开发
```bash
npm install
npm run build # tsc → dist/
npm run typecheck
npm test # 44 个测试,含 mock 管控面 + 真实 stdio 端到端
```
测试不需要真实的阿里云账号:`test/mock-e2b.ts` 起了一个本地 HTTP 服务模拟 E2B 兼容的管控面。
## License
MIT © 2026 dophinowo
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues