TractorBeeam365 MCP

TractorBeeam365 MCP

一个用于 Veeam Backup for Microsoft 365 (VB365) 的 Model Context Protocol 服务。 它会直接调用 VB365 REST API，让 MCP 客户端（Claude Code / Claude Desktop）能够检查备份配置、发现保护缺口、识别趋势、验证云不可变性——并在你明确选择启用后，运行作业和编排还原。

独立项目——与 Veeam Software 无关联，未获其认可或支持。“Veeam”是 Veeam Software 的注册商标；“Beeam”的拼写是刻意采用的、别具一格的文字游戏。使用风险由你自行承担。

🔱 名称由来：tractor beam 会把你的数据拉回来，而 Beeam 则巧妙呼应了底层的备份产品。默认采用安全的只读检查；“拉回”（还原/操作）需选择启用。

两种模式

模式	默认状态	功能
只读检查	✅ 始终启用	仅 GET 请求。无法进行任何更改。配置/运行状况、缺口分析、趋势、云锁定交叉核验。
操作/还原	⛔ 关闭	通过 TB_* 环境变量选择启用。运行/停止作业、生成报告、同步组织、定义并执行还原。所有写入操作都需要确认令牌，并会记录审计日志。

如果你从未设置 TB_* 环境变量，这就是一个纯只读检查工具，从根本上无法修改你的环境——操作/还原工具甚至不会注册。

快速部署（预构建镜像）

无需克隆或构建。从 v2.2.0 起，镜像以**多架构版本（amd64 + arm64）**发布到 GitHub Container Registry 和 Docker Hub，因此可在 x86 服务器、Apple Silicon 和 ARM 设备（Raspberry Pi、ARM 云环境）上原生运行。 在 ARM 主机上，请固定使用 :2.2.0（或更高版本）标签，直到发布多架构的 :latest 标签。

持久化 HTTP 服务（Docker Compose）

获取两个文件并启动：

curl -fsSLO https://raw.githubusercontent.com/Ringosystems/TractorBeeam-MCP/main/docker-compose.deploy.yml
curl -fsSL  https://raw.githubusercontent.com/Ringosystems/TractorBeeam-MCP/main/.env.example -o .env
# Edit .env: set VB365_HOST / VB365_USERNAME / VB365_PASSWORD and a long MCP_AUTH_TOKEN.
docker compose -f docker-compose.deploy.yml up -d

随后 MCP 会在 http://<host>:8766/mcp 上运行。使用你设置的 bearer 令牌连接客户端：

claude mcp add --transport http tractorbeeam365 http://<host>:8766/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

稍后更新：

docker compose -f docker-compose.deploy.yml pull && docker compose -f docker-compose.deploy.yml up -d

Unraid（一键部署）

在 Unraid 中打开 Docker → Add Container，然后将此模板 URL 粘贴到 Template 字段：

https://raw.githubusercontent.com/Ringosystems/TractorBeeam-MCP/main/deploy/unraid/tractorbeeam365.xml

填写 VB365_HOST、VB365_USERNAME、VB365_PASSWORD 和较长的 MCP_AUTH_TOKEN，然后点击 Apply。审计和下载文件夹会映射到 /mnt/user/appdata/tractorbeeam365/。

单个 MCP 客户端，无需服务（stdio）

对于由客户端自行启动服务的情况，可通过 stdio 按需运行镜像：

docker run -i --rm \
  -e VB365_HOST=... -e VB365_USERNAME=... -e VB365_PASSWORD=... \
  ghcr.io/ringosystems/tractorbeeam-mcp:latest

只读工具（始终可用）

工具	返回内容
vb365_health_summary	一次性检查：组织、作业及最近状态、存储库、云存储（B2/S3/Azure）、代理、许可证、趋势异常和 flags 列表。从这里开始。
vb365_trends	各作业的成功/失败趋势变化、存储库容量耗尽预测、各组织的还原测试频率、RPO 合规性。
gap_coverage_summary / gap_unprotected_objects	通过对比 Microsoft Graph 与作业的保护范围，查看备份覆盖率及未受保护的 M365 实时对象（需要 GRAPH_*）。
cloud_lock_audit	交叉核验存储桶的 Object Lock 模式/保留期/版本控制与 VB365 的报告是否一致（需要 B2_*/S3_*）。
vb365_api_root	资源列表和版本（用于确认连接）。
vb365_list_organizations / vb365_org_inventory	受保护的组织；某个组织的用户/组/站点/团队。
vb365_list_jobs / vb365_get_job / vb365_job_scope	作业、单个作业的配置，以及作业确切保护的内容（选定/排除）。
vb365_list_job_sessions	最近的运行结果（可按作业筛选）。
vb365_list_repositories / vb365_list_restore_points	存储库（容量/保留期/不可变性）；还原点。
vb365_list_object_storage / vb365_get_object_storage	云/对象存储（B2/S3/Azure/Wasabi/IBM/Glacier）。
vb365_list_proxies / vb365_license	代理及其状态；许可证/版本/到期时间。
vb365_get	对任何其他 /<version>/... 资源执行只读 GET 请求。

操作 / 还原工具（选择启用，受开关控制）

仅在设置相应开关时注册。**两次调用确认模式：**先调用一次以获取预览和一次性 confirm_token；再次调用时传入 confirm=<token> 即可执行。每次执行都会追加到 TB_AUDIT_LOG。

工具（开关）	功能
action_job（TB_ALLOW_JOB_CONTROL）	启动 / 停止 / 启用 / 禁用备份作业
action_generate_report（TB_ALLOW_REPORTS）	将邮箱 / onedrive / sharepoint / teams / 用户保护、许可证、存储报告生成到文件
action_org_sync（TB_ALLOW_ORG_SYNC）	触发组织的目录重新同步
action_proxy（TB_ALLOW_PROXY）	重新扫描代理或将其切换到维护模式
restore_session_start → restore_browse / restore_search → restore_define → restore_execute → restore_status → restore_session_stop（TB_ALLOW_RESTORE）	跨 Exchange / OneDrive / SharePoint / Teams 完整编排还原：打开某个时间点的会话，浏览 / 搜索可还原项目，然后定义（选择项目 + 目标位置 + 选项）并执行还原。

还原：定义还原什么、还原到哪里、如何还原

restore_session_start(scope="job", scope_id="<jobId>", workload="exchange")
   → { session_id }                         # opens a point-in-time explore session
restore_browse(session_id)                  # list mailboxes
restore_browse(session_id, parent_id=<mailboxId>)   # list items in a mailbox
restore_define(session_id, parent_id=<mailboxId>, item_ids=[...], target="export")
   → { confirm_token, preview }             # DRY RUN — nothing changed
restore_execute(session_id, confirm=<confirm_token>)   # executes + audits
restore_session_stop(session_id)

• target = export（最安全 — 将备份读取到本地文件；无需 M365 凭据）、alternate（写入到其他 M365 位置）或 original（写回原始位置 — 具有破坏性；还需传入 confirm_overwrite_original=True）。
• options 可携带备用 mailbox / folder，以及 VB365 用于写回的 M365 目标凭据（userName / userPassword / applicationId），也可以在 .env 中设置 VB365_RESTORE_*。
• PST 导出需要在 VB365 服务上安装 64 位 Outlook 2010+（这是 Veeam 的要求）；未安装时，exportToPst 会返回服务器端错误。

设置

1. 在 Claude Code 运行的位置安装 Python 3.10+。

2. 在此文件夹中：

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   

3. 将 .env.example 复制为 .env，并填写 VB365_HOST、VB365_USERNAME、VB365_PASSWORD（除非你的设置不同，否则保留 VB365_PORT=4443、VB365_API_VERSION=v8）。也可选填 GRAPH_*、B2_* / S3_* 和 TB_* 开关。

   REST API 账户需要是 VB365 管理员（或还原操作员）——VB365 没有只读 API 角色。只读审查工具始终仅使用 GET 请求。New-VB365ReviewAccount.ps1 可在 VB365 服务上创建专用服务账户。请勿将 .env 纳入源代码管理。

在 Claude Code 中注册

# Replace <repo> with the absolute path to your clone.
claude mcp add tractorbeeam365 --scope user -- "<repo>\.venv\Scripts\python.exe" "<repo>\server.py"

在 Linux/macOS 上使用正斜杠和 <repo>/.venv/bin/python。

该项目也已发布到 MCP Registry，名称为 io.github.Ringosystems/tractorbeeam-mcp（GHCR 上的 OCI 镜像），因此支持该注册表的 MCP 客户端可以直接安装。要将已发布的镜像作为 stdio 服务运行：

docker run -i --rm \
  -e VB365_HOST=... -e VB365_USERNAME=... -e VB365_PASSWORD=... \
  ghcr.io/ringosystems/tractorbeeam-mcp:latest

然后询问：“运行 VB365 健康状况摘要，并告诉我是否存在配置错误。”

启用操作 / 还原层

操作 / 还原工具默认隐藏，需选择启用。在 .env 中：

TB_ENABLE_ACTIONS=true        # master switch
TB_ALLOW_JOB_CONTROL=true     # + any of the per-category flags you want
TB_ALLOW_RESTORE=true
TB_AUDIT_LOG=audit/actions.jsonl

除非同时设置 TB_ALLOW_WRITE_OVER_HTTP=true，否则不会通过 HTTP 传输注册操作 / 还原工具，因为该传输没有针对每个调用方的身份标识。请通过 stdio 运行操作员层，或仅在你自己的身份验证反向代理之后运行。

安全模型：仅在启用时才注册工具；每次变更都需要使用一次性确认令牌进行第二次调用；还原默认使用安全目标位置（覆盖原始位置需要明确确认）；并且每项操作都会写入只追加的审计日志。建议：单独运行一个启用了这些开关的“操作员”实例，并让默认实例保持只读。

作为持久服务运行（Docker / UNRAID）

镜像本身默认使用 stdio 传输（因此 MCP 客户端可以通过 docker run -i 运行它）。通过 docker compose，它会在容器内的 0.0.0.0:8000 上运行 streamable-http，只读（不使用任何 TB_* 标志）。镜像中未内置凭据。 HTTP 传输采用默认拒绝策略：除非设置 MCP_AUTH_TOKEN（客户端随后发送 Authorization: Bearer <token>），或明确接受风险并设置 MCP_ALLOW_UNAUTHENTICATED_HTTP=true，否则拒绝启动。

# Put MCP_AUTH_TOKEN=<a long random secret> in .env first.
docker compose up -d --build          # builds locally and runs read-only
# MCP is live at http://<host>:8766/mcp ; attach with:
claude mcp add --transport http tractorbeeam365 http://<host>:8766/mcp \
  --header "Authorization: Bearer <token>"

预构建镜像

每个 GitHub Release 都会通过 CI（.github/workflows/publish.yml） 将支持多种架构和多个标签的镜像发布到 GHCR、Docker Hub 和 MCP Registry。完整的发布操作手册见 PUBLISHING.md。

# GitHub Container Registry (published automatically on every release):
docker pull ghcr.io/ringosystems/tractorbeeam-mcp:latest
# Docker Hub (published when the DOCKERHUB_USERNAME / DOCKERHUB_TOKEN repo
# secrets are configured):
docker pull ringosystems/tractorbeeam365-mcp:latest

如需手动发布：

docker build -t <dockerhubuser>/tractorbeeam365-mcp:latest .
docker push <dockerhubuser>/tractorbeeam365-mcp:latest

**安全：**MCP HTTP 传输无法识别各个调用方的身份。此构建默认绑定到回环地址， 并要求先设置 MCP_AUTH_TOKEN 才能提供 HTTP 服务；除非设置 TB_ALLOW_WRITE_OVER_HTTP=true，否则会通过 HTTP 隐藏写入/还原工具。 仍请将端口限制在可信网络内，并在前端配置 TLS + 身份验证。审计 日志以及生成的 PST/报告文件存放在挂载的 audit/ 和 downloads/ 卷中。请参阅 SECURITY.md。

快速连接测试（无需 MCP 客户端）

.\.venv\Scripts\Activate.ps1
python -c "import server; print(server.vb365_api_root())"

备注

• .gitignore 会排除 .env、虚拟环境以及操作员层级的 audit/、 downloads/、*.pst 文件。切勿提交凭据或还原的数据。
• VB365 随附自签名证书，因此 VB365_VERIFY_SSL 默认值为 false。这 会使到 VB365 的连接容易受到主动中间人攻击，因此建议将 VB365_CA_BUNDLE 设置为服务器证书（并针对该证书启用验证），或在使用受信任证书时设置 VB365_VERIFY_SSL=true。如果连接未经验证，服务器会在启动时发出警告。
• 端点名称会因 VB365 版本而略有不同。如果某个精选工具返回 404，请调用 vb365_api_root，并使用 vb365_get 配合准确的资源名称。

商标

这是一个独立项目，与以下任何公司均无关联，也未获其认可或赞助。产品名称仅用于 识别（指称性使用）。

• “Veeam”是 Veeam Software 的注册商标。“Beeam”这一拼法是刻意使用的不同文字游戏， 并非该商标。
• Microsoft、Microsoft 365、Microsoft Graph、Outlook 和 Office Deployment Tool 均为 Microsoft 集团公司的商标。
• Backblaze 和 B2 是 Backblaze, Inc. 的商标。
• Amazon Web Services、AWS、Amazon S3 和 S3 Glacier 是 Amazon.com, Inc. 或其关联公司的商标。
• Wasabi、IBM 和 IBM Cloud、Azure 以及 Google Cloud 均为其 各自所有者的商标。

许可证

本项目根据 MIT License 发布。安全模型和报告方式请参阅 SECURITY.md，贡献方式请参阅 CONTRIBUTING.md， 发布版本的构建和发布方式请参阅 PUBLISHING.md。