TractorBeeam365 MCP

A Model Context Protocol server for Veeam Backup for Microsoft 365 (VB365). It talks directly to the VB365 REST API so an MCP client (Claude Code / Claude Desktop) can review your backup configuration, find protection gaps, spot trends, verify cloud immutability — and, when you explicitly opt in, run jobs and orchestrate restores.

Independent project — not affiliated with, endorsed by, or supported by Veeam Software. "Veeam" is a registered trademark of Veeam Software; the "Beeam" spelling is a deliberate, distinct play on words. Use at your own risk.

🔱 The name: a tractor beam pulls your data back in — and Beeam winks at the backup product underneath. Read-only review is the safe default; the "pull" (restore/actions) is opt-in.

Two tiers

If you never set the TB_* flags, this is a pure read-only reviewer that physically cannot modify your environment — the action/restore tools aren't even registered.

Quick deploy (prebuilt image)

No clone or build required. From v2.2.0 the image is published multi-arch (amd64 + arm64) to GitHub Container Registry and Docker Hub, so it runs natively on x86 servers, Apple Silicon, and ARM boxes (Raspberry Pi, ARM cloud). On an ARM host, pin the :2.2.0 (or later) tag until a multi-arch :latest has been published.

Persistent HTTP service (Docker Compose)

Grab two files and start it:

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 is then live at http://<host>:8766/mcp. Attach a client with the bearer token you set:

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

Update later:

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

Unraid (one click)

In Unraid open Docker → Add Container, and paste this template URL into the Template field:

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

Fill in VB365_HOST, VB365_USERNAME, VB365_PASSWORD, and a long MCP_AUTH_TOKEN, then Apply. The audit and downloads folders map under /mnt/user/appdata/tractorbeeam365/.

Single MCP client, no service (stdio)

For a client that launches the server itself, run the image on demand over stdio:

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

Read-only tools (always available)

Action / Restore tools (opt-in, gated)

Registered only when the matching flag is set. Two-call confirm pattern: call once to get a preview + a one-time confirm_token; call again with confirm=<token> to execute. Every execution is appended to TB_AUDIT_LOG.

Restore: define what, where, how

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 (safest — reads backup to a local file; no M365 creds), alternate (writes to a different M365 location), or original (writes back to the original location — destructive; also pass confirm_overwrite_original=True).
• options may carry an alternate mailbox/folder and the M365 target credentials VB365 uses to write back (userName/userPassword/applicationId), or set VB365_RESTORE_* in .env.
• PST export requires 64-bit Outlook 2010+ installed on the VB365 server (a Veeam requirement); without it, exportToPst returns a server-side error.

Setup

1. Install Python 3.10+ where Claude Code runs.

2. From this folder:

   powershell

   Copy

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

3. Copy .env.example to .env and fill in VB365_HOST, VB365_USERNAME, VB365_PASSWORD (keep VB365_PORT=4443, VB365_API_VERSION=v8 unless yours differ). Optionally add GRAPH_*, B2_*/S3_*, and the TB_* flags.

   The REST API account needs to be a VB365 administrator (or restore operator) — VB365 has no read-only API role. The read-only review tools are GET-only regardless. New-VB365ReviewAccount.ps1 creates a dedicated service account on the VB365 server. Keep .env out of source control.

Register with 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"

On Linux/macOS use forward slashes and <repo>/.venv/bin/python.

It is also published to the MCP Registry as io.github.Ringosystems/tractorbeeam-mcp (an OCI image on GHCR), so MCP clients that support the registry can install it directly. To run the published image as a stdio server:

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

Then ask: "Run a VB365 health summary and tell me if anything is misconfigured."

Enabling the action / restore tier

The action/restore tools stay hidden until you opt in. In .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

The action/restore tools are not registered over an HTTP transport unless you also set TB_ALLOW_WRITE_OVER_HTTP=true, because that transport has no per-caller identity. Run the operator tier over stdio, or only behind your own authenticating reverse proxy.

Safety model: tools are only registered when enabled, every mutation needs a second call with a one-time confirm token, restores default to a safe target (original-location overwrite needs an explicit acknowledgement), and every action is written to an append-only audit log. Recommended: run a separate "operator" instance with the flags on, and the default instance read-only.

Run as a persistent service (Docker / UNRAID)