aliyun-agent-sandbox-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aliyun-agent-sandbox-mcp Run a script that prints the first 10 rows of a sample pandas dataframe"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
aliyun-agent-sandbox-mcp
阿里云智能体沙箱(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
工具一览
工具 | 说明 |
| 打印当前 Endpoint 配置与 API Key 是否就绪(不联网) |
| 创建沙箱,返回 |
| 按状态 / 模板列出沙箱 |
| 查看单个沙箱状态、规格与到期时间 |
| 延长沙箱 TTL |
| 销毁沙箱,释放资源 |
| 在沙箱内执行 Shell 命令,返回 stdout / stderr / exitCode |
| 在 Jupyter 内核里执行代码,返回日志、富结果与 traceback |
| 读取文本文件,支持 |
| 写入文件(自动建父目录,可选追加) |
| 列出目录内容(类型 + 大小) |
| 递归创建目录 |
| 重命名 / 移动文件或目录 |
| 删除文件或目录 |
快速开始
1. 准备阿里云侧资源
按官方文档依次完成:
创建 API Key(形如
e2b_xxx)
并确认目标地域已开通 Agent Sandbox 极速版。
2. 配置环境变量
export E2B_API_KEY="e2b_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export REGION="cn-hangzhou" # 可选,默认 cn-hangzhouE2B_DOMAIN 与 E2B_API_URL 默认由 REGION 推导:
变量 | 默认值 |
|
|
|
|
需要自定义时再显式设置:
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]配置项
环境变量 | 默认值 | 说明 |
| — | 必填,Agent Sandbox 控制台创建的 API Key |
|
| 地域,决定默认域名与 API 地址 |
|
| 沙箱域名 |
|
| 控制面 API 地址 |
|
| 默认模板 |
|
| 默认沙箱 TTL(毫秒) |
|
| 单次工具返回的最大字符数 |
| — | 指向一个 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
Available Tools
14 toolsfile_listList a directoryARead-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 fileBRead-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 directoryBDestructive
Delete a file or directory inside the sandbox. Irreversible.
Inputs: path (required), sandbox_id.
file_renameRename or move a pathCDestructive
Rename or move a file or directory inside the sandbox.
Inputs: to (required), from (required), sandbox_id.
file_writeWrite a fileBDestructive
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 sandboxADestructive
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 commandADestructive
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 sandboxARead-only
Return state, template, resource size and expiry for one sandbox.
Inputs: sandbox_id (required).
sandbox_killKill a sandboxADestructive
Terminate a sandbox immediately and release its resources. Irreversible.
Inputs: sandbox_id (required).
sandbox_listList sandboxesARead-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 configurationARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Cloud Linux VMs for your agent: run code, Docker, files and HTTPS previews in a Sandboxer microVM.
Deploy and manage Jade Hosting projects from AI clients. Jade account and OAuth required.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with cloud-based execution environments through Alibaba Cloud's Wuying infrastructure, enabling browser automation, file operations, and terminal access in secure, serverless cloud environments.7MIT
- AlicenseAqualityDmaintenanceEnables AI agents to create, modify, and deploy web projects through the AICre8 platform's sandbox environment. It supports project management, code generation, and direct shell command execution for streamlined web development.711 npmMIT
- AlicenseAqualityDmaintenanceEnables AI assistants to securely execute Python and JavaScript code in sandboxed environments, with file management and package installation.755 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to operate a persistent Linux sandbox in the cloud, running commands, managing files, using Git, and publishing artifacts through a Streamable HTTP MCP endpoint.-