Skip to main content
Glama
aliyun-agent-sandbox-mcp

aliyun-agent-sandbox-mcp

aliyun-agent-sandbox-mcp

npm license node

阿里云智能体沙箱(Agent Sandbox)的 MCP Server —— 让 Claude、Cursor、Cline、DeepSeek Harness 等支持 Model Context Protocol 的 AI 客户端,直接在自己的对话里创建云端沙箱、 执行 Shell 命令、跑 Python / JavaScript 代码、读写文件。

阿里云 Agent Sandbox 极速版兼容 E2B 协议,因此本项目的连接层直接复用官方 e2b / @e2b/code-interpreter SDK,只把 Endpoint 换成阿里云地域域名,并在其上封装出一层贴合 大模型调用习惯的 MCP 工具。

官方文档:https://help.aliyun.com/zh/agent-sandbox/using-the-cloud-sandbox-via-the-sdk


特性

  • 14 个 MCP 工具:沙箱生命周期、命令执行、代码解释器、文件系统全覆盖

  • 两种使用模式:显式 sandbox_id 复用长生命周期沙箱,或省略 sandbox_id 每次调用自动创建 / 销毁临时沙箱

  • 多语言代码执行:Python / JavaScript / TypeScript / Bash / R / Java(依赖 code-interpreter-v1 模板)

  • 零硬编码:全部走环境变量或 .env 文件,不会把 API Key 写进代码

  • 输出有界:单次工具返回超长时自动截断(头 + 尾保留),避免撑爆上下文

  • 仅需 Node.js ≥ 20.19.0,通过 npx 零安装运行

  • TypeScript 编写,带类型声明与单元测试

Related MCP server: AICre8 MCP Server

工具一览

工具

说明

sandbox_status

打印当前 Endpoint 配置与 API Key 是否就绪(不联网)

sandbox_create

创建沙箱,返回 sandbox_id

sandbox_list

按状态 / 模板列出沙箱

sandbox_info

查看单个沙箱状态、规格与到期时间

sandbox_set_timeout

延长沙箱 TTL

sandbox_kill

销毁沙箱,释放资源

run_command

在沙箱内执行 Shell 命令,返回 stdout / stderr / exitCode

run_code

在 Jupyter 内核里执行代码,返回日志、富结果与 traceback

file_read

读取文本文件,支持 offset / limit 分页

file_write

写入文件(自动建父目录,可选追加)

file_list

列出目录内容(类型 + 大小)

file_make_dir

递归创建目录

file_rename

重命名 / 移动文件或目录

file_remove

删除文件或目录

快速开始

1. 准备阿里云侧资源

按官方文档依次完成:

  1. 配置 RAM 用户权限

  2. 创建 Team

  3. 创建 API Key(形如 e2b_xxx)

并确认目标地域已开通 Agent Sandbox 极速版。

2. 配置环境变量

export E2B_API_KEY="e2b_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export REGION="cn-hangzhou"          # 可选,默认 cn-hangzhou

E2B_DOMAIN 与 E2B_API_URL 默认由 REGION 推导:

变量

默认值

E2B_DOMAIN

<region>.sandbox.aliyuncs.com

E2B_API_URL

https://api.<region>.sandbox.aliyuncs.com

需要自定义时再显式设置:

export E2B_DOMAIN="cn-hangzhou.sandbox.aliyuncs.com"
export E2B_API_URL="https://api.cn-hangzhou.sandbox.aliyuncs.com"

3. 自检

npx -y aliyun-agent-sandbox-mcp --check

输出示例:

region:   cn-hangzhou
domain:   cn-hangzhou.sandbox.aliyuncs.com
apiUrl:   https://api.cn-hangzhou.sandbox.aliyuncs.com
template: code-interpreter-v1
timeout:  300000 ms
apiKey:   configured

接入 MCP 客户端

Claude Desktop / Claude Code

{
  "mcpServers": {
    "aliyun-agent-sandbox": {
      "command": "npx",
      "args": ["-y", "aliyun-agent-sandbox-mcp"],
      "env": {
        "E2B_API_KEY": "e2b_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "REGION": "cn-hangzhou"
      }
    }
  }
}

Cursor / Cline / Continue

同上,把 mcpServers 片段写进各自配置(Cursor:~/.cursor/mcp.json)。

从源码运行

git clone https://github.com/adorablelovelymia/aliyun-agent-sandbox-mcp.git
cd aliyun-agent-sandbox-mcp
npm install
npm run build
node dist/index.js --check

然后把 command 换成 node,args 换成 ["/绝对路径/dist/index.js"]。

使用示例(对话里可以直接这样说)

帮我创建一个沙箱,在里面跑一下这段 pandas 代码,把结果给我看。

AI 客户端会自动串起工具调用:

sandbox_create(template="code-interpreter-v1", timeout_ms=600000)
  -> sandbox_id: sbx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

run_code(sandbox_id="sbx-...", language="python", code="import pandas as pd; ...")
  -> 45

sandbox_kill(sandbox_id="sbx-...")

不想显式管理沙箱时,直接省略 sandbox_id:

run_command(command="uname -a && python3 --version")
  -> Linux ... x86_64 GNU/Linux
     Python 3.11.x
     [exitCode: 0]

配置项

环境变量

默认值

说明

E2B_API_KEY

—

必填,Agent Sandbox 控制台创建的 API Key

REGION

cn-hangzhou

地域,决定默认域名与 API 地址

E2B_DOMAIN

<region>.sandbox.aliyuncs.com

沙箱域名

E2B_API_URL

https://api.<region>.sandbox.aliyuncs.com

控制面 API 地址

E2B_TEMPLATE

code-interpreter-v1

默认模板

SANDBOX_TIMEOUT_MS

300000

默认沙箱 TTL(毫秒)

SANDBOX_MAX_OUTPUT_CHARS

30000

单次工具返回的最大字符数

SANDBOX_ENV_FILE

—

指向一个 dotenv 文件,读取上述变量

环境变量优先级高于 dotenv 文件。

命令行

aliyun-agent-sandbox-mcp              # 启动 MCP stdio server(默认行为)
aliyun-agent-sandbox-mcp --check      # 打印配置并校验,未配置 Key 时退出码为 1
aliyun-agent-sandbox-mcp --help
aliyun-agent-sandbox-mcp --version

开发

npm install
npm run build          # tsc -> dist/
npm run typecheck
npm run test:unit      # 离线单元测试
npm run test:integration   # 需要 E2B_API_KEY,会真实创建/销毁沙箱

集成测试的完整输出:

Discovered 14 tools: sandbox_status, sandbox_create, sandbox_list, sandbox_info,
sandbox_kill, sandbox_set_timeout, run_command, run_code, file_read, file_write,
file_list, file_make_dir, file_remove, file_rename

  ok   sandbox_status reports the endpoint
  ok   sandbox_create returns an id
  ok   run_command runs a shell command
  ok   run_code runs Python in the kernel
  ok   run_code runs JavaScript
  ok   file_write writes a file
  ok   file_read reads it back
  ...
ALL CHECKS PASSED

运行环境要求

Node.js ≥ 20.19.0。

下界不是随手写的:上游 e2b 的 CJS 产物里用 require() 加载 ESM 的 chalk, 而 require(ESM) 要到 Node 20.19.0 才默认开启。在 20.18.1 上启动会直接抛 ERR_REQUIRE_ESM。本项目已在 20.19.0 / 22.12.0 / 26.13.1 上验证通过。

注意事项

  • 沙箱按使用时长计费,用完请调用 sandbox_kill;临时沙箱模式会在工具返回前自动销毁。

  • 极速版单沙箱默认最长运行 86400s,磁盘 15GB,详见使用限制。

  • 本项目只是 MCP 封装层,不修改阿里云官方 SDK 行为;协议兼容性问题请以官方文档为准。

License

MIT

Available Tools

14 tools
file_listList a directoryA
Read-only

List the entries of a directory inside the sandbox with type and size.

Inputs: path (required), sandbox_id.

file_make_dirCreate a directoryB

Create a directory (recursively) inside the sandbox.

Inputs: path (required), sandbox_id.

file_readRead a fileB
Read-only

Read a text file from the sandbox. Use offset/limit to page through large files.

Inputs: path (required), limit, offset, sandbox_id.

file_removeRemove a file or directoryB
Destructive

Delete a file or directory inside the sandbox. Irreversible.

Inputs: path (required), sandbox_id.

file_renameRename or move a pathC
Destructive

Rename or move a file or directory inside the sandbox.

Inputs: to (required), from (required), sandbox_id.

file_writeWrite a fileB
Destructive

Create or overwrite a file inside the sandbox. Parent directories are created automatically.

Inputs: path (required), content (required), append, sandbox_id.

run_codeExecute code in the sandboxA
Destructive

Execute Python/JavaScript/TypeScript/Bash/R/Java in the sandbox Jupyter kernel and return stdout, stderr, rich results and any error traceback. Requires a code-interpreter template. When sandbox_id is omitted a temporary sandbox is created and killed afterwards.

Inputs: code (required), language, sandbox_id, timeout_ms.

run_commandRun a shell commandA
Destructive

Run a shell command inside the sandbox and return stdout, stderr and the exit code. When sandbox_id is omitted a temporary sandbox is created for the call and killed afterwards.

Inputs: command (required), cwd, envs, sandbox_id, +1 more.

sandbox_createCreate a sandboxA

Create a new Alibaba Cloud Agent Sandbox (阿里云智能体沙箱) and return its sandbox_id. Keep the ID to reuse the sandbox in later tool calls, and call sandbox_kill when done. Defaults to the code-interpreter-v1 template with a 5 minute TTL.

Inputs: envs, metadata, template, timeout_ms.

sandbox_infoInspect a sandboxA
Read-only

Return state, template, resource size and expiry for one sandbox.

Inputs: sandbox_id (required).

sandbox_killKill a sandboxA
Destructive

Terminate a sandbox immediately and release its resources. Irreversible.

Inputs: sandbox_id (required).

sandbox_listList sandboxesA
Read-only

List sandboxes in the configured region, optionally filtered by state or template. Note: the control-plane list endpoint is eventually consistent, so a sandbox created moments ago may not appear yet.

Inputs: limit, state, template.

sandbox_set_timeoutExtend the sandbox TTLA

Update the time-to-live of a running sandbox so long jobs are not reaped while they run.

Inputs: sandbox_id (required), timeout_ms (required).

sandbox_statusCheck Agent Sandbox configurationA
Read-only

Show the Alibaba Cloud Agent Sandbox endpoint configuration this server will use (region, domain, API URL, default template) and whether E2B_API_KEY is set. Does not call the network.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation4/5

    Tool families are clearly separated: sandbox lifecycle (status/create/list/info/kill/set_timeout), execution (run_code vs run_command, distinguished by Jupyter kernel vs shell), and file operations. The only mild overlap is sandbox_status (server config, no network) versus sandbox_info (state of a specific sandbox), but the descriptions make the distinction explicit.

    Naming Consistency4/5

    Names group into predictable prefixes: sandbox_* for lifecycle, file_* for filesystem work, and run_* for execution, with consistent snake_case throughout. Minor deviations exist (run_code/run_command are not prefixed, and sandbox_status/sandbox_info use a noun rather than a verb), but the pattern remains readable and predictable.

    Tool Count5/5

    Fourteen tools map cleanly onto three coherent concerns (sandbox lifecycle, code/command execution, file management), with no redundant entries. Each tool covers a distinct operation an agent would plausibly need.

    Completeness4/5

    The surface covers the full sandbox lifecycle (create, list, inspect, extend TTL, kill), two execution modes, and a near-complete filesystem set (read, write, list, mkdir, remove, rename). Gaps are minor: no local-to-sandbox file upload/download, no binary or archive transfer, and no pause/resume of a sandbox.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers