内容
# MEGA 云端 MCP 服务器
一个 MCP 服务器，允许 AI 助手通过封装 [MEGAcmd](https://github.com/meganz/MEGAcmd) 命令行界面来操作 **MEGA** 云账户。它与任何 MCP 客户端配合使用：作为一个 **Claude Desktop Extension**（`.mcpb`）进行一键安装，并通过标准 MCP 服务器配置在 **OpenAI Codex** 或任何其他 MCP 客户端上运行。
## 安全模型（不可协商）
- **登录从不通过 AI 进行。** 没有登录工具，也没有工具接受密码。你在 MEGAcmd 交互式 shell 中进行**带外**身份验证（`login <email>`，隐藏密码提示）；该服务器仅发出已经身份验证的 `mega-*` 命令。
- **永远不会返回或记录会话/凭证材料。** `mega_whoami` 只显示你的账户电子邮件。`mega_account` 运行 `whoami -l` 以读取计划层级，但一个封闭的允许列表解析器仅返回计划 + 存储 — 原始 `session` ID、主/恢复密钥和支付数据永远不会返回。
- 破坏性和数据移动操作（`rm`、`deleteversions`、`export`、`share`、`get`、`put`、`mv`）通过两调用令牌协议进行**确认门控**。
> [!IMPORTANT]
> **这些防护措施仅在 MCP 层强制执行 — 它们不会隔离 MEGAcmd 本身。** 它们限制了 AI 可以通过此服务器的工具执行的操作。如果你在具有 shell/终端访问权限的 CLI 或代码代理中运行此服务器，则该代理可以完全绕过此服务器，并直接调用 `mega-*` 二进制文件针对你已经身份验证的 MEGAcmd 会话。
> 这会访问账户安全命令，此服务器故意不公开这些命令 — 例如 `passwd`（更改你的账户密码）和 `masterkey`（打印你的主/恢复密钥）— 以及数据移动和会话命令，它通常会确认门控（`rm`、`export`、`share`、`logout`、`killsession`），而无需确认提示。MEGAcmd 保持一个共享的本地会话，因此**你机器上的任何可以运行 `mega-*` 的进程都以你的身份运行。**
>
> 仅在你信任其 shell 访问权限的代理中启用此服务器。诸如 Claude Desktop 之类的仅限工具的 MCP 客户端没有 shell，因此此绕过方式不适用。
## 隐私政策
此连接器受 MEGA 的隐私政策管辖：**<https://mega.io/privacy>**。
此扩展程序对你的数据执行以下操作：
- **在本地运行。** MCP 服务器和它驱动的 MEGAcmd 引擎完全在你的机器上运行。此扩展程序没有后端，不会向其作者发送任何数据。
- **凭证。** 你的 MEGA 电子邮件/密码在带外输入到你自己的终端（MEGAcmd 交互式 shell，隐藏提示）并且**永远不会**通过 AI 或此连接器传递。没有登录/凭证工具存在。登录会话仅由 MEGAcmd 在其本地配置（`~/.megaCmd`）中存储；此扩展程序永远不会读取、返回或传输它。
- **到达 AI 模型的内容。** 像任何工具使用一样，你/模型提供的参数和工具返回的结果作为对话的一部分发送到你的 AI 提供商 — 例如，你列出的文件夹，你执行的操作的路径，或你创建的公共链接。扩展程序故意仅返回请求的 操作结果（列表被限制）并且永远不会发送本地文件内容或会话数据。
- **MEGAcmd 下载。** 在首次使用时，扩展程序从 MEGA 自己的服务器下载 MEGAcmd（`https://mega.nz`）并在运行前验证它；不会收集任何遥测数据。
- **保留/共享。** 此扩展程序仅存储你设备上的 MEGAcmd 的本地缓存/会话，不与任何第三方共享。根据该提供商的条款处理发送给你的 AI 提供商的数据。
- **联系方式：** <https://mega.io/contact>。
## 入门指南
在你的 MCP 客户端中安装服务器：
- **Claude Desktop：** 双击 `mega-cloud-mcp.mcpb` 并批准它。
- **OpenAI Codex 插件：** 此仓库包含 Codex 插件包装器文件：`.codex-plugin/plugin.json` 和 `.mcp.json`。Codex 包装器运行已检查的单文件包 `dist/plugin-server.js`，因此已安装的插件不需要 `node_modules`。在源代码更改后使用 `npm install && npm run build:plugin` 重建该包。包装器**不需要**在公共 GitHub 上，除非你希望其他人或远程市场从该源安装它。
- **OpenAI Codex / 其他 MCP 客户端：** 构建服务器（`npm install && npm run build`），然后将其注册为标准 stdio MCP 服务器 — 例如，在 `mcpServers` 配置块中：
```json
{
"mcpServers": {
"mega": { "command": "node", "args": ["/absolute/path/to/dist/index.js"] }
}
}
```
（请参阅客户端文档以获取其确切的 MCP 配置语法 — 例如，Codex 使用 `~/.codex/config.toml`。可选设置作为 `env` 变量传递；请参见 `manifest.json` 中的 `MEGA_MCP_*` 密钥。）
然后，在任何客户端：
1. 仅限首次：当工具报告 MEGAcmd 不可用时，运行 **`megacmd_setup`** 并批准一次性下载。它在运行任何操作之前验证 MEGAcmd 的代码签名并且**不**登录。
2. **带外**登录（你的密码从不通过 AI）：`mega_whoami` 打印确切的命令 — 打开它命名的 MEGAcmd 交互式 shell 并运行 `login <your-email>`，在隐藏的提示中输入你的密码。然后重试。
3. 你已设置 — 请求助手处理你的 MEGA 文件。
## 示例提示
- "列出我的 MEGA 云驱动器并显示我正在使用的存储空间。"
- "查找 /Documents 下的所有 PDF 文件，并在上周内修改。"
- "将 ~/Reports/q2.xlsx 上传到 /Work/Reports，然后为其创建公共链接。"
（助手将要求你确认上传和链接，然后再执行。）
- "我的 MEGA 计划是什么，何时续期？"
## 要求
- Node.js >= 18
- MEGAcmd — 在首次使用时自动获取（参见下文）。不需要单独安装。
## MEGAcmd 的获取方式
`.mcpb` 保持轻量级并且**不**捆绑 MEGAcmd。相反，服务器按以下顺序定位 MEGAcmd 二进制文件：
1. 捆绑（`vendor/megacmd/<platform-arch>/`，如果有的话）
2. 用户配置的目录（`megacmd_dir` 设置）
3. **标准 OS 安装**（macOS：`/Applications/MEGAcmd.app`）
4. 用户特定的**缓存**（如果标准位置不可写入，则使用备用方案）
5. 系统 `PATH`
`megacmd_setup` 在首次使用时为你安装 MEGAcmd，**在运行任何操作之前验证它**。它经过确认门控（你批准一次性下载）并且从不登录。它安装到**标准位置**，因此 OS 的 MEGAcmd 客户端会原生自动启动服务器。
各平台状态：
- **macOS** — 完全实施并验证。安装 MEGAcmd.app 到 `/Applications`（如果 `/Applications` 不可写入，则回退到用户特定的缓存）。完整性：开发者 ID 代码签名 + notarization（团队 `T9RH74Y7L9`）在执行前验证。可选的 SHA-256 固定值（MEGA 不发布任何固定值）；设置 `MEGA_MCP_DOWNLOAD_SHA256` 以强制执行固定值。
- **Windows** — 已实施；正在进行设备验证。下载官方 MEGAcmd NSIS 安装程序，在运行之前验证其 Authenticode 签名（签名者组织 `Mega Limited`），然后通过 `explorer.exe` 启动它，以便 MEGAcmd **独立**安装到实际的 `%LOCALAPPDATA%\MEGAcmd` — 在 MSIX 包容器之外，因此其服务器自动启动功能正常，共享会话。安装是交互式的：完成对话框，然后重试（`megacmd_setup` 在检测到之前报告“安装中”的状态）。
- **Linux** — 标准安装需要 root 权限（`apt`/`dnf`），连接器无法为您执行此操作，因此 `megacmd_setup` 指导您通过包管理器（来自 <https://mega.io/cmd>）安装 MEGAcmd；然后连接器在 `PATH` 上检测到它。
由于 MEGAcmd 从 MEGA 自己的服务器下载（不由该扩展程序重新分发），因此不适用 BSD/GPL 重新分发问题。
## 卸载/清理
删除连接器**不**会自动删除 MEGAcmd 或您的会话（MCPB 没有卸载钩子）。要完全清理：
1. 注销（使会话失效）：运行 `mega_logout` 工具，在终端中运行 `mega-logout`，或在 MEGA 应用程序中撤销会话（设置 → 会话）。
2. 删除引擎：将 `/Applications/MEGAcmd.app` 拖到回收站（macOS）/ 删除软件包（Linux）/ 删除 `~/Library/Caches/mega-cloud-mcp` （如果使用缓存备用方案）。
3. 如果需要，删除会话存储：删除 `~/.megaCmd`。
## 开发
```bash
npm install
npm run build # tsc -> dist/
npm run build:plugin # bundle Codex 插件服务器 -> dist/plugin-server.js
npm test # vitest 单元测试（不需要实时 MEGAcmd）
npm run typecheck
# 针对已构建的服务器进行端到端 stdio 烟雾测试：
node scripts/smoke-stdio.mjs
node scripts/smoke-stdio.mjs mega_whoami '{}'
# 构建一个可安装的 Claude Desktop 扩展（.mcpb）：
npm run pack # build -> stage -> validate -> pack => mega-cloud-mcp.mcpb
```
要执行实时 MEGA 操作，您必须（1）安装 MEGAcmd 并（2）自己在 MEGAcmd 交互式 shell 中登录（`login <email>`）。服务器会自动检测到带外会话。
## 工具
- 设置：`megacmd_setup`（在首次使用时下载 + 验证 MEGAcmd；确认门控）
- 只读（自动）：`mega_whoami`、`mega_account`、`mega_df`、`mega_ls`、`mega_find`、`mega_tree`、`mega_du`、`mega_mount`、`mega_transfers`、`mega_version`、`mega_mediainfo`、`mega_attr`、`mega_errorcode`
- 只读（自动），同步/备份状态：`mega_sync_list`、`mega_backup_list`、`mega_sync_issues`、`mega_sync_config`
- 只读匹配选项：`ls`/`find` 接受 `usePcre`（Perl 正则表达式）。破坏性/导出操作（`rm`/`export`/`share`/`get`）也接受 `usePcre`，但首先在确认预览中显示匹配的节点集。
- 变更（自动）：`mega_mkdir`、`mega_cp`
- 设置：`mega_config`（显示自动；更改值需要确认门控；拒绝关闭 HTTPS）
- 确认门控：`mega_mv`、`mega_put`、`mega_get`、`mega_thumbnail`、`mega_rm`、`mega_deleteversions`、`mega_export`（创建/删除）、`mega_share`（添加/删除）、`mega_logout`、`mega_killsession`、`mega_attr_set`、`mega_userattr_set`、`mega_user_remove`、`mega_user_verify`、`mega_transfer_control`、`mega_invite`、`mega_ipc`、`mega_import`、`mega_sync_add`、`mega_sync_control`、`mega_sync_ignore`（添加/删除）、`mega_backup_add`、`mega_backup_control`
- 仅需选择（`expose_contacts`，默认为关闭 — 显示联系人 PII）：`mega_users`、`mega_showpcr`、`mega_userattr`
- 仅需选择（`expose_account_details`，默认为关闭 — 显示您自己的登录元数据 + 财务 PII）：`mega_sessions`、`mega_balance`
- 仅需选择（`expose_file_contents`，默认为关闭 — 将文件内容带入对话）：`mega_cat`（读取文件文本，限制为 1 MB / 最大 10 MB，仅限文本）。文件内容被视为不受信任的数据；破坏性/导出工具仍然受到确认门控，因此嵌入式指令不会导致无声伤害。
`mega_account` 运行 `whoami -l`（计划层级的唯一来源），但仅通过封闭的允许列表解析器返回计划 + 存储 — 会话列表、余额和支付历史记录永远不会显示。登录凭证、主/恢复密钥和可续签会话 ID 通过设计永远无法通过任何工具访问。
纯文本输出解析器（`ls`、`df`、`find` 和只读工具）编写时带有防御性，并受到单元测试的保护。
## 许可证
包装器源码：MIT。MEGAcmd（在运行时下载，不重新分发）具有混合许可证：该项目调用的组件 — 后台服务器、非交互式客户端、`mega-*` 包装器和 `mega-exec` 分发器 — 为 BSD-2-Clause（一些 IPC 源为 BSD-2-Clause / GPL-3.0）；交互式 MEGAcmd shell 为 GPL-3.0，不在此调用或重新分发。参见 `LICENSE` 和 `NOTICE`。
