Skip to main content
Glama

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.

npm CI 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(见文档)。

但 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 可控

Related MCP server: microsandbox-mcp

快速开始

1. 准备百炼沙箱

  1. 开通阿里云百炼,进入 Sandbox,完成一次 SLR 服务授权。

  2. 在「我的模版」创建模版(镜像三选一:code-interpreter-v1 / browser / all-in-one),记下 templateCode。

  3. 在 Sandbox 页左下角生成 API Key(sk-...)。

  4. 记下控制台右上角的 工作空间 ID(形如 llm-xxxxxxxx)与账号 UID。

2. 配置 MCP 客户端

npx -y bailian-sandbox-mcp

大多数客户端的配置格式如下(以 Claude Desktop / Cursor / Cline 为例):

{
  "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)

鉴权方式(与官方文档一致):

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,请在客户端侧确认交互策略。

开发

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to create, manage, and execute code in isolated Firecracker microVM sandboxes via the MCP protocol, with support for sandbox lifecycle and file operations.
      4
      Apache 2.0
    • -
      license
      Not graded
      quality
      B
      maintenance
      Exposes f2b-sandbox capabilities as MCP tools for creating, managing, and running commands in sandboxes, enabling AI agents to execute code and manipulate files in isolated environments.
      -