MCP 服务器

AutoDL MCP Server

Enables management of AutoDL GPU resources including instance lifecycle, balance queries, elastic deployments, and notifications through typed MCP tools.

README

让 Codex 安全、可解释地管理 AutoDL GPU 资源。

Typed MCP tools · Documentation-aware Skill · Confirmation gates · Credential redaction

</div>

这是什么？

AutoDL Plugin 是一个面向 Codex 的社区插件，把 AutoDL 官方开发者 API 与完整帮助文档封装成两层能力：

AutoDL MCP Server：26 个参数明确、可校验的工具，负责查询余额、管理容器实例 Pro、操作弹性部署、查询镜像/GPU 库存、读取时长包、发送微信通知和获取容器指标。
AutoDL Skill：让 Agent 理解 AutoDL 的计费、数据保留、系统盘/数据盘、镜像、网络、SSH、CUDA、训练环境和权限边界，并在高风险操作前执行正确流程。

它不是简单的“HTTP 接口转发器”。插件会区分只读、状态变更、计费和破坏性操作；在真正创建、开机、关机、释放、扩缩容、删除或发送消息前，必须经过确认门。

[!IMPORTANT] 这是社区集成，不是 AutoDL 官方产品。实际服务能力、价格、库存、配额和规则以 AutoDL 官网与官方文档为准。

亮点

26 个 typed MCP 工具：每个接口都有独立名称、参数说明和输入校验。
安全确认门：变更操作在 confirm=false 时只返回请求预览，不访问 AutoDL。
凭据保护：实例详情默认遮盖 root_password 与 jupyter_token。
Token 隔离：开发者 Token 只从本地环境读取，不进入源码、工具输出或测试夹具。
完整文档认知：索引官方帮助站 103/103 个页面、463 个搜索条目。
文档漂移检查：可重新抓取官方目录并生成页面状态和 SHA-256 清单。
真实 MCP 测试：通过 stdio 握手调用全部工具，而不是只测内部函数。
正式环境只读验证：余额、Pro 实例列表和 Pro 镜像列表已经通过真实 AutoDL API 验证。

架构

flowchart LR
    U["User / Codex"] --> S["AutoDL Skill"]
    S -->|"选择工具与安全流程"| M["Typed MCP Server"]
    M --> G{"Confirmation gate"}
    G -->|"只读"| A["AutoDL Developer API"]
    G -->|"变更且 confirm=true"| A
    G -->|"confirm=false"| P["Request preview only"]
    A --> R["Redaction + structured result"]
    R --> U
    D["103 official docs pages"] --> S

快速开始

1. 克隆并安装

git clone https://github.com/wuzihuang/AUTODL-PLUGIN.git
cd AUTODL-PLUGIN
npm install

要求：Node.js 20 或更高版本。

2. 配置 AutoDL Token

在 AutoDL 控制台的账号设置中获取开发者 Token，然后创建本地环境文件：

cp .env.example .env

编辑 .env：

AUTODL_TOKEN=你的开发者Token

.env 已被 Git 忽略。不要把真实 Token 写进 README、配置示例、Issue、日志或提交记录。

也可以不创建 .env，而是在启动 Codex 的环境中提供：

export AUTODL_TOKEN='你的开发者Token'

3. 在 Codex 中加载插件

在支持本地插件的 Codex 中选择这个仓库根目录。Codex 会通过：

.codex-plugin/plugin.json 发现 AutoDL Skill；
.mcp.json 启动本地 AutoDL MCP Server。

如果你的客户端暂时不支持本地插件，可手动配置 MCP：

{
  "mcpServers": {
    "autodl": {
      "command": "bash",
      "args": ["/absolute/path/AUTODL-PLUGIN/scripts/start-mcp.sh"],
      "cwd": "/absolute/path/AUTODL-PLUGIN"
    }
  }
}

Skill 也可以单独安装：

cp -R skills/autodl ~/.codex/skills/autodl

4. 试着这样问

“查看我的 AutoDL 余额，金额换算成人民币元。”
“列出我的 Pro 实例，告诉我哪些还在计费。”
“查询 westDC2 的 RTX 4090 弹性部署库存。”
“我要创建一个单卡实例，先给我参数和费用风险预览，不要直接创建。”
“保存这个实例的环境之前，我还需要单独备份哪些数据？”
“为什么 nvidia-smi 的 CUDA 版本和环境里的 CUDA 不一样？”

MCP 工具一览

账户与存储

工具	作用	类型
`autodl_wallet_balance`	获取余额、累计消费与代金券余额	只读
`autodl_switch_exclusive_nfs`	切换专用 NFS / 普通文件存储	需确认

容器实例 Pro

工具	作用	类型
`autodl_pro_create_instance`	创建按量计费 Pro 实例	计费、需确认
`autodl_pro_instance_snapshot`	获取实例硬件、使用率与连接信息	只读、默认脱敏
`autodl_pro_instance_status`	获取实例状态	只读
`autodl_pro_list_instances`	分页列出实例	只读
`autodl_pro_power_on`	GPU 模式开机	计费、需确认
`autodl_pro_power_off`	关机	需确认
`autodl_pro_release_instance`	永久释放实例	破坏性、需确认
`autodl_pro_save_image`	保存系统盘为私有镜像	需确认
`autodl_pro_list_private_images`	查询 Pro 私有镜像与保存状态	只读

弹性部署

工具	作用	类型
`autodl_esd_list_private_images`	获取可用于弹性部署的私有镜像	只读
`autodl_esd_create_deployment`	创建 ReplicaSet、Job 或 Container	计费、需确认
`autodl_esd_list_deployments`	查询部署	只读
`autodl_esd_list_container_events`	轮询容器生命周期事件	只读
`autodl_esd_list_containers`	查询容器、状态与连接信息	只读
`autodl_esd_stop_container`	停止指定容器	需确认
`autodl_esd_set_replica_num`	调整 ReplicaSet 副本数	计费/中断风险、需确认
`autodl_esd_stop_deployment`	停止整个部署	需确认
`autodl_esd_delete_deployment`	停止并永久删除部署	破坏性、需确认
`autodl_esd_set_blacklist`	将异常容器所在主机加入调度黑名单	需确认
`autodl_esd_list_blacklist`	获取生效中的调度黑名单	只读
`autodl_esd_gpu_stock`	查询地区 GPU 总量和空闲量	只读
`autodl_esd_ddp_overview`	获取已购时长包余额	只读

通知与监控

工具	作用	类型
`autodl_send_wechat_message`	向账号绑定的微信发送通知	外部消息、需确认
`autodl_local_metrics`	获取容器 CPU、内存和 GPU 指标	只读、需在容器内可达

完整字段、接口路径、地区代码、GPU 规格和基础镜像示例见 API Reference。

权限矩阵

能力	常规 Token	个人/企业实名认证	企业认证与产品权限
账户余额	✓	✓	✓
容器实例 Pro		✓	✓
弹性部署			✓
弹性部署 GPU 库存			✓
容器性能监控			✓
微信通知	需绑定微信	需绑定微信	需绑定微信

如果 API 返回“无当前资源访问权限”，插件会解释为认证或产品权限问题，而不是把它误报成 MCP 故障。

安全模型

确认门

所有会产生费用、改变状态、停止工作负载、删除数据或发送外部消息的工具都有 confirm 参数：

confirm=false  → 返回方法、路径、目标与参数预览，不发送网络请求
confirm=true   → 执行真实 AutoDL API 请求

Agent 仍应在执行前向用户说明：

准确的实例、部署或容器 ID；
GPU 数、实例数或副本数；
价格上限和计费影响；
是否中断训练或服务；
是否已经备份系统盘和数据盘。

数据与凭据

root_password、jupyter_token 默认显示为 [REDACTED]。
本地指标请求不会携带 AutoDL 开发者 Token。
Token 不会出现在 MCP 结构化结果和错误结果中。
释放实例与删除部署被标记为 destructive。
Pro 实例释放流程要求先关机。

AutoDL 使用边界

严禁将资源用于虚拟货币挖矿。
本地系统盘和数据盘没有冗余可靠性承诺，重要数据必须备份。
映射服务地址应保持私密，并遵守 AutoDL 自定义服务协议。
当前价格、活动、库存、地区、配额和政策日期必须实时核实。

更多规则见 Operations Guide 和 Security Policy。

关键技术细节

API Host：https://api.autodl.com
鉴权：Authorization: <raw token>，不加 Bearer
成功判断：code === "Success"
金额：API 中的相关整数除以 1000 才是人民币元
CUDA 编码：例如 118 表示 CUDA 11.8
Pro 状态/详情：官方文档定义为 GET + JSON body
GPU 库存：按单卡调度口径，不能证明多卡位于同一台主机
专用 NFS：mountable=1；切回普通文件存储：mountable=-1

配置

环境变量	默认值	说明
`AUTODL_TOKEN`	无	必填，AutoDL 开发者 Token
`AUTODL_BASE_URL`	`https://api.autodl.com`	开发者 API 根地址
`AUTODL_WEB_BASE_URL`	`https://www.autodl.com`	微信消息接口根地址
`AUTODL_METRICS_URL`	`http://127.0.0.1:2022/autopanel/v1/api/monitor/current`	容器本地指标地址
`AUTODL_REQUEST_TIMEOUT_MS`	`20000`	请求超时，毫秒

测试

全量自动测试

npm test

测试包括：

Codex plugin manifest 与 MCP 配置校验；
Skill frontmatter、引用文件和 26/26 工具覆盖；
103/103 官方文档页面清单；
MCP stdio 初始化与工具发现；
26/26 工具完整 mock 调用；
HTTP 方法、路径、query 和 GET JSON body；
未确认变更不发网；
AutoDL 业务错误映射；
Token 不泄漏；
实例凭据默认遮盖；
本地指标请求不携带 Token。

正式环境只读测试

npm run test:live

这个命令只读取余额、实例、镜像、部署和黑名单等信息，不创建或修改资源。企业接口没有权限时会标为 SKIP/PERMISSION。

当前验证记录：

账户余额：HTTP 200
Pro 实例列表：HTTP 200
Pro 私有镜像列表：HTTP 200
弹性部署：测试账号无访问权限，安全跳过
Pro 状态/详情：测试账号无现存实例，条件跳过

详见完整测试报告。

官方文档覆盖

文档刷新脚本读取 AutoDL 的 MkDocs 搜索索引，逐页检查正文，并生成：

当前快照：

指标	数量
搜索索引条目	463
实际页面	103
可访问页面	103
核心 API 操作	24
帮助站补充 API	2

刷新：

npm run docs:refresh
npm test

仓库不会整站复制 AutoDL 文档，只保存路由索引、摘要规则和哈希元数据。涉及价格、认证、库存、配额与政策时应重新查看官方页面。

项目结构

AUTODL-PLUGIN/
├── .codex-plugin/plugin.json      # Codex 插件清单
├── .mcp.json                      # MCP 自动发现配置
├── assets/                        # Logo 与 README Banner
├── mcp/
│   ├── src/                       # MCP Server 与 AutoDL HTTP Client
│   └── test/                      # 全工具契约测试、只读实时测试
├── skills/autodl/
│   ├── SKILL.md                   # Agent 工作流与安全规则
│   ├── references/                # API、运维规则、文档索引
│   └── scripts/                   # 文档刷新与 Skill 校验
├── scripts/
│   ├── start-mcp.sh               # 插件 MCP 启动入口
│   └── validate-plugin.mjs        # 插件与敏感信息校验
├── docs/TEST_REPORT.md
└── .github/workflows/ci.yml

开发与贡献

欢迎补充新公开接口、响应样例、权限说明和文档漂移修复。请先阅读 CONTRIBUTING.md。

基本流程：

npm install
npm test

新增状态变更接口时必须：

使用独立 typed tool；
加入 confirm 预览门；
描述计费、中断和数据影响；
增加 mock 契约测试；
不使用真实账户执行破坏性 CI 测试。

License

MIT

AutoDL 名称、服务和官方文档归其权利人所有。本项目仅提供社区集成，不代表 AutoDL 官方背书。

<div align="center"> Built for careful automation: inspect first, confirm changes, preserve data. </div>