idrive-mcp-server

一个 MCP（模型上下文协议）服务器，将 iDrive 的 Web 备份/恢复控制台暴露为工具，供兼容 MCP 的 AI 助手（例如 Claude Desktop 或 Claude Code）使用。它通过从已登录浏览器复制的会话 cookie 与 iDrive 未公开的内部 Web API 通信——即 idrive.com 控制台本身调用的那些端点——因为 iDrive 不为此控制台提供公共 API 或 OAuth 流程。有关此服务器所基于的逆向工程端点参考，请参阅 docs/api-map.md。

获取 IDRIVE_COOKIE

1. 在浏览器中登录 idrive.com。

2. 打开 DevTools -> Network 选项卡。

3. 点击发送到 www.idrive.com 的任何 XHR 请求。

4. 复制该请求的 Cookie 头的完整值。

5. 将其放入 .env 文件（复制 .env.example）中，格式为 IDRIVE_COOKIE=<value>。

此 cookie 包含一个会话令牌（SES_TOKEN，一个 JWT），大约 24 小时后过期——过期后，工具调用将失败并显示明确的“刷新你的会话”错误，你需要重复上述步骤。

Related MCP server: Google Drive MCP Server

在 Claude Code / Claude Desktop 中配置

在你的 MCP 配置中添加一个条目（Claude Code 使用 .mcp.json，Claude Desktop 使用 claude_desktop_config.json）：

{
  "mcpServers": {
    "idrive": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/idrive-mcp-server",
      "env": {
        "IDRIVE_COOKIE": "<your cookie value>"
      }
    }
  }
}

或者，在运行 npm run build 之后，将 command/args 指向构建输出：

{
  "mcpServers": {
    "idrive": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/idrive-mcp-server",
      "env": {
        "IDRIVE_COOKIE": "<your cookie value>"
      }
    }
  }
}

可用工具

• list_devices — 无输入。列出在已认证的 iDrive 账户下备份的每台设备（设备 ID、操作系统、昵称、IP 地址和备份存储桶位置），通过 EVS 托管的 evs/listDevices 端点实现。除了 IDRIVE_COOKIE 之外，无需任何额外配置。

• list_files — deviceId（必需）、path（默认 "/"）、osType（默认 "win"）。通过 iDrive 的 getRestoreData 端点浏览设备的备份文件树。

• browse_folder — deviceId（必需）、path（必需，EVS 格式："/C"、"/C/Users/..."）。通过更丰富的 EVS 托管端点 evs/browseFolder 浏览设备的备份文件夹（在 list_files 的基础上增加了回收站/校验和/实时镜像字段）。请先使用 list_files 发现设备可用的驱动器号/根目录，因为从未观察到 evs/browseFolder 处理裸根路径。

• get_thumbnail — deviceId（必需）、path（必需，与 browse_folder 相同的 EVS 格式）、timestamp（必需——来自先前 list_files/browse_folder 调用的文件的 lmd_web 值）。通过 EVS 托管的 evs/getThumbnail 端点获取备份文件的缩略图预览图像，作为 MCP 图像内容返回。

• download_file — deviceId（必需）、path（必需，与 browse_folder 相同的 EVS 格式）。通过 EVS 托管的 evs/downloadFile 端点下载备份文件的实际内容，作为 base64 编码的 MCP 资源内容返回。iDrive 在此端点上的 Content-Type 不可信，无法用于识别真实文件类型——请根据文件名/扩展名推断。

• get_file_properties — deviceId（必需）、path（必需，与 browse_folder 相同的 EVS 格式）。通过 EVS 托管的 evs/getProperties 端点获取单个备份文件或文件夹的大小/最后修改时间元数据。

• get_file_versions — deviceId（必需）、path（必需，与 browse_folder 相同的 EVS 格式）。通过 EVS 托管的 evs/getVersions 端点列出文件的先前备份版本。目前仅确认了“无版本历史”的响应形状——没有先前版本的文件会作为正常结果报告（hasVersions: false），而不是工具错误；真实版本列表的形状尚未确认，并以原始 JSON 返回。

• get_account_usage — 无输入。返回账户的已用/总 Sync 存储配额，作为原始字符串（例如 "0.00 KB"、"5000.00 GB"），从 iDrive 的 account.html 页面上的两个内联 <script> 变量中抓取——没有专用的 JSON 使用量端点。本质上很脆弱（是 HTML 抓取，不是稳定的 API），并且特别反映了页面自身的“Sync”配额命名；它是否也代表设备备份的总使用量尚未确认。

变更工具

以下工具会更改账户上的真实备份数据，与上述所有工具（均为只读）不同。它们的描述和 MCP annotations 明确说明了这一点（readOnlyHint: false，以及 delete_file 的 destructiveHint: true）。

• create_folder — deviceId（必需）、parentPath（必需，EVS 格式，必须是现有文件夹）、folderName（必需——仅新文件夹的名称，不是路径）。通过 EVS 托管的 evs/createFolder 端点在设备的实时备份中创建新文件夹。已确认有效：新文件夹会出现在后续的 browse_folder/list_files 列表中。

• delete_file — deviceId（必需）、paths（必需，一个或多个 EVS 格式路径的数组——在单个批量调用中作为重复的 p 字段发送）、permanent（可选，默认 false）。通过 EVS 托管的 evs/v1/deleteFile 端点从设备的实时备份中删除文件/文件夹。permanent: false（默认）将路径移动到回收站——已确认有效，并且可以使用 restore_from_trash 恢复。permanent: true 发送 trash=no，推测（根据字段名称/模式）表示永久、不可恢复的删除，但这从未被独立确认有效——在依赖它之前请将其视为未验证。

• restore_from_trash — deviceId（必需）、paths（必需，一个或多个 EVS 格式路径的数组，与 delete_file 相同的重复 p 批量处理）。通过 EVS 托管的 evs/putBackFromTrash 端点将先前删除的文件/文件夹恢复到其原始位置。已确认有效。没有确认的方法来枚举回收站中当前的内容，因此 paths 必须已知。

所有 EVS 托管的工具（browse_folder、get_thumbnail、download_file、get_file_properties、get_file_versions、list_devices、create_folder、delete_file、restore_from_trash）都会透明地引导并缓存 EVS 卫星主机所需的 EVSID 会话（参见 docs/api-map.md 中的“EVSID：EVS 会话实际如何建立”部分）——除了 IDRIVE_COOKIE 之外，无需额外配置，但它们确实需要 cookie 中的 EVS_SERVER 值（存在于从 /idrive/home 复制的 cookie 中，不一定存在于从 idriveent 控制台复制的 cookie 中）才能知道要引导哪个 EVS 主机。

测试

npm test 无条件运行单元测试，外加一组受环境变量门控的实时集成测试，未设置时干净地跳过：

• IDRIVE_COOKIE — 任何集成测试运行所必需。

• IDRIVE_TEST_DEVICE_ID — 大多数集成测试需要的真实 device_id（来自 list_devices）。

• IDRIVE_TEST_EVS_PATH — 大多数集成测试浏览/读取的真实 EVS 格式路径（例如 /C）。

• IDRIVE_TEST_ALLOW_MUTATIONS=1 — 一个单独的、明确的 opt-in，在上述三个变量之外，src/tools/files.test.ts 中的 create_folder/delete_file/restore_from_trash 集成测试才会运行。该测试会变更真实账户：它在 IDRIVE_TEST_EVS_PATH 下创建一个唯一命名的临时文件夹（因此重复运行不会冲突），针对它练习所有三个工具，并在测试结束前通过将其移动到回收站进行清理——即使断言中途失败（try/finally）。如果此变量未设置为精确的 "1"，该测试将被跳过，因此仅设置了 IDRIVE_COOKIE/IDRIVE_TEST_DEVICE_ID/IDRIVE_TEST_EVS_PATH 进行只读测试的开发人员可以运行 npm test，而无需担心它会触及真实数据。

get_account_usage 的集成测试是只读的，只需要 IDRIVE_COOKIE，与其他账户工具相同。

状态

配置加载、会话过期检测和共享 HTTP 客户端（src/client/idriveClient.ts）已就位；MCP 工具正在 src/tools/ 下增量添加（参见上面的“可用工具”）。