Read-only MCP server for BorgBackup operational status?

[rfv-370]

HI,

I am using an Hermes agent to help me in admin tasks - read only and with his own user/sshkey- to check backups.
Is there anybody who implemented a read-only MCP server for BorgBackup, exposing safe status and metadata ?
this MCP Server would:

• list configured repositories from an allow-list
• list archives
• latest archive info
• repository info
• retention preview
• progress/status from a local backup job
• no prune/delete/compact/repair/restore by default
• no passphrase exposure
• no raw file listing unless explicitly enabled

that would be helpful.

It could work for any other agent - claude, chatgpt, etc...

I would also be happy if maintainers think this should live as a separate companion project, for example borgbackup-mcp, rather than in Borg core. The important point for me is to define a safe read-only interface for operational agents.

Let me know

Best,

Robert

[ThomasWaldmann]

I was tempted to implement MCP for borg2, but I have some doubts:

Assume something goes wrong with AI agent usage on your system, like it accidentally deleting files or databases. Then you'ld need your backups.

It could also happen that AI agent usage leads to disclosure of information. That would be already bad for data from your life filesystem and even worse if it also included historical data from backups (and maybe even from backups of other systems).

Implementing MCP only for read-only operations (or in general: stuff that is considered harmless, like you suggested) would limit the damage an agent could do with the existing code, but what would keep the agent back from just adding the "missing" MCP functionality, following what it finds in the existing code?

Also: agents are also quite good with CLI interfaces (and use --help if they want to know more), so maybe MCP is not needed?

Another thing is that borg usually does push backups (client with data trusted, server not trusted). But if there is some rogue agent on your system, the client is not trusted anymore, so this doesn't match borg's threat model.

[ThomasWaldmann]

Note: if the repository is remote (like rest://borg@backupserver in borg2), permissions to the repo can be enforced server-side, so that some specific ssh key only gets ready-only access.

[rfv-370]

Hi Thomas,
my agent as always is own user on server with no elevation and his own ssh key. when/if it needs elevation I work out a specific script to give access solely to some command via a dedicated script - like for checking containers for example which requires elevation.
Yes CLI is fine as well, actually currently my agent is using a dedicated scripts which it has access to after it has logged (with no elevation possible).

[rfv-370]

MCP may or may not be need, just the issue is that some of the CLI may require elevation to check few things and this requires extra work for me - the human in the loop! :-)
with an MCP we could have the MCP server deal with what requires elevation - to read- and then give back the info ...?

[ThomasWaldmann]

just the issue is that some of the CLI may require elevation to check few things and this requires extra work for me - the human in the loop

Practical examples for this?

[rfv-370]

Thanks — the practical use case is narrower than “let an AI operate Borg”.

I have now implemented the first version without MCP, using restricted CLI wrappers. That may well be the safer and sufficient solution.

In my setup, Borg runs as root through systemd on a Raspberry Pi backup host. It reads several read-only NFS exports and sends encrypted backups to remote storage. An admin agent connects over SSH as its own unprivileged Unix user. It has no general sudo access.

Some useful status information is nevertheless root-owned: selected systemd state, process state, log metadata and progress information. Rather than give the agent general CLI or log access, I expose only two root-owned wrappers through exact sudoers rules:

sudo -n /usr/local/sbin/borg-watch-status
sudo -n /usr/local/sbin/borg-audit-status

The wrappers do not execute Borg. They only inspect selected local state and return sanitized derived fields. They do not expose raw logs, filenames, archive names, source paths, repository URLs or IDs, SSH configuration, credentials, or complete process command lines.

A typical result is:

health=running
health_detail=fresh_progress
service_state=active
borg_process_state=D
progress_stale=no
io_interpretation=d_state_fresh_progress

One concrete benefit is correct interpretation of Linux D-state. Borg may be waiting on NFS or disk I/O for a long time while still making progress. A generic agent could incorrectly report that as a hung backup. The wrapper combines process state with sanitized numeric-progress freshness and reports d_state_fresh_progress.

Other practical queries are:

Is the backup service running, inactive, failed or disabled?
Is a Borg process present?
Is numeric progress fresh or stale?
Are all expected source mounts present and read-only?
Is completion evidence present after the service exits?
Is the current state healthy, warning, failed, or indeterminate?

The agent can report or escalate these conditions, but it cannot start or stop services, mount filesystems, inspect backup contents, or run prune, compact, delete, extract, mount, restore, or check --repair.

So I agree that MCP is not required for this. The restricted wrapper is already a valid implementation and probably the right first step.

Where MCP might still help is as a standardized typed interface for several agent clients or several backup hosts. For example, instead of every agent parsing host-specific text, and having me or other human admin creating wrappers all around, an MCP tool could return a small versioned schema:

{
"health": "running",
"health_detail": "fresh_progress",
"service_state": "active",
"progress_stale": false,
"process_state": "D"
}

However, I do not consider MCP itself a security boundary. A safe design would keep the MCP process unprivileged and have it call the same immutable, root-owned, allow-listed status wrappers. It should expose a fixed set of read-only tools, accept no arbitrary Borg arguments, have no raw-log or repository-content tool, and have no method for dynamically adding capabilities. - for example?

If the agent can modify the MCP implementation, its configuration, the wrappers, or the sudoers policy, then the read-only claim is indeed meaningless. Those components therefore need to be owned and deployed by a different administrative boundary from the agent. - hence the fact that my agent(s) do not have by default sudo ability on system they connect to.

My current conclusion is that this would make more sense, if useful to others, as a small companion project rather than Borg core. The actual requirement is to "Allow a low-privilege monitoring agent to inspect sanitized backup health without raw backup data, broad sudo access, or any destructive Borg capability."

I hope these examples clarify the intended scope. The existing CLI-wrapper approach may ultimately be enough; an MCP adapter would mainly provide schema standardization and agent interoperability.

[rfv-370]

I can share a private link to a codex chat with you in private if you think it is relevant ?
example of the result from my current wrapper with Oscar (an hermes 0.19 implementation) - I just asked him "check the Borg backup status on gesser" (gesser being my rpi managing the job). - usefull for me at least as I need just my phone to check what is going on.

[ThomasWaldmann]

I just gave it a try as a separate project: https://github.com/borgbackup/borg-mcp

[rfv-370]

Thanks Thomas.
I will try it and report there.
_/_
:-)