URBackup MCP
# PointlessPOS UrBackup MCP
[](https://www.gnu.org/licenses/gpl-3.0)
An [MCP](https://modelcontextprotocol.io) server for [UrBackup](https://www.urbackup.org) —
manage your backup server from any MCP client (Claude Desktop, Open WebUI, etc.).
Built directly against the UrBackup web API, with the full action surface extracted
from the backend source (see [`docs/api-reference.md`](docs/api-reference.md)).
> This solution was authored by a self-hosted-focused Point of Sale solution provider.
> This and other self-hosted solutions are provided by [PointlessPOS](https://pointlesspos.com).
## Features
| Area | Tools |
|---|---|
| Status | `urbackup_status`, `urbackup_status_check` |
| Backups | `urbackup_start_backup`, `urbackup_progress`, `urbackup_stop_process`, `urbackup_list_backups` |
| Browse/restore | `urbackup_browse_backup_files`, `urbackup_restore_files`, `urbackup_restore_image`, `urbackup_download_file_url`, `urbackup_download_zip_url` |
| Backup lifecycle | `urbackup_archive_backup`, `urbackup_unarchive_backup`, `urbackup_delete_backup` |
| Logs | `urbackup_get_logs`, `urbackup_get_log` |
| Settings | `urbackup_get_general_settings`, `urbackup_save_general_settings`, `urbackup_get_client_settings`, `urbackup_save_client_settings`, `urbackup_get_mail_settings`, `urbackup_save_mail_settings` |
| Users | `urbackup_list_users`, `urbackup_create_user`, `urbackup_change_user_rights`, `urbackup_change_user_password`, `urbackup_remove_user` |
| Usage | `urbackup_usage_stats`, `urbackup_usage_graph` |
| Misc | `urbackup_add_extra_client`, `urbackup_shutdown` |
Destructive operations (restore, delete, settings changes, user changes, shutdown)
require an explicit `confirm=true` parameter.
## Tested with
- **Open WebUI** — both as a remote MCP server (streamable HTTP + Bearer token) and as an OpenAPI tool
- **Qwen 3.8 27B**
## Install
```bash
pip install -e .
```
## Configure
Environment variables:
| Variable | Default | Description |
|---|---|---|
| `URBACKUP_URL` | `https://localhost:55414` | Server URL (default ports: 55413 HTTP, 55414 HTTPS) |
| `URBACKUP_USER` | *(empty)* | Admin username (empty = anonymous, if the server allows) |
| `URBACKUP_PASS` | *(empty)* | Admin password |
| `URBACKUP_VERIFY_SSL` | `true` | Set `false` for self-signed certificates |
| `URBACKUP_MCP_TRANSPORT` | `stdio` | `stdio` (default) or `streamable-http` (for Open WebUI / remote MCP) |
| `URBACKUP_MCP_HOST` | `127.0.0.1` | Bind host for `streamable-http` (use `0.0.0.0` to reach from other machines) |
| `URBACKUP_MCP_PORT` | `8765` | Port for `streamable-http` |
| `URBACKUP_MCP_BEARER_TOKEN` | *(empty)* | **Required** for `streamable-http`; clients send `Authorization: Bearer <token>` |
## Run
```bash
urbackup-mcp
# or
python -m urbackup_mcp.server
```
A `.env` file in the project root (or current directory) is loaded automatically —
see `.env.example`.
### Open WebUI (remote MCP server + Bearer token)
Open WebUI's MCP integration connects to a **remote** MCP server over HTTP and can
send a **Bearer** token. So run the server in `streamable-http` mode and put the
same token in Open WebUI's Bearer field.
1. Set in `.env` (or export):
```
URBACKUP_MCP_TRANSPORT=streamable-http
URBACKUP_MCP_HOST=0.0.0.0
URBACKUP_MCP_PORT=8765
URBACKUP_MCP_BEARER_TOKEN=<your-long-random-token>
```
2. Start it:
```bash
python -m urbackup_mcp.server
# → urbackup-mcp streamable-http on http://0.0.0.0:8765/mcp (Bearer auth)
```
3. In Open WebUI → **Settings → MCP Servers → Add**: type **Remote**, URL
`http://<this-host>:8765/mcp`, and paste the same value into the **Bearer** field.
The endpoint enforces the token: no/wrong token → `401`, correct token → `200`.
### Open WebUI (OpenAPI tool — recommended)
Open WebUI's *OpenAPI* integration fetches `<url>/<path>` and calls the listed
operations with the Bearer token. The server therefore also exposes an OpenAPI
bridge (spec version 3.0, which Open WebUI's parser requires) over the same tools:
- `GET /openapi.json` and `GET /mcp/openapi.json` — the spec (all 31 tools)
- `POST /tools/{name}` and `POST /mcp/tools/{name}` — run a tool (Bearer auth)
In **Settings → Tools → Add Tool → OpenAPI** use:
| Field | Value |
|-------|-------|
| URL | `http://<server-ip>:8765/mcp` (no trailing slash, no leading space) |
| Path | `openapi.json` |
| Auth | Bearer Token → the `URBACKUP_MCP_BEARER_TOKEN` value |
(When Open WebUI runs on the Docker host and this server in a container, use
the container's bridge IP, e.g. `http://172.17.0.2:8765/mcp`.)
### Running as a service (systemd)
```ini
# /etc/systemd/system/urbackup-mcp.service
[Unit]
Description=URBackup MCP server (streamable HTTP)
After=network-online.target
[Service]
WorkingDirectory=/opt/urbackup-mcp
EnvironmentFile=/opt/urbackup-mcp/.env
ExecStart=/opt/urbackup-mcp/.venv/bin/python -m urbackup_mcp.server
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
### Running as a service (Docker)
```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir .
EXPOSE 8765
CMD ["python", "-m", "urbackup_mcp.server"]
```
```bash
docker run -d --name urbackup-mcp \
-p 8765:8765 \
-e URBACKUP_URL=https://backup.example.com:55414 \
-e URBACKUP_USER=admin \
-e URBACKUP_PASS=secret \
-e URBACKUP_MCP_TRANSPORT=streamable-http \
-e URBACKUP_MCP_BEARER_TOKEN=<your-long-random-token> \
urbackup-mcp
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"urbackup": {
"command": "python",
"args": ["-m", "urbackup_mcp.server"],
"env": {
"URBACKUP_URL": "https://backup.example.com:55414",
"URBACKUP_USER": "admin",
"URBACKUP_PASS": "secret",
"URBACKUP_VERIFY_SSL": "false"
}
}
}
}
```
## Development
```bash
python -m venv .venv && . .venv/bin/activate
pip install -e .
# end-to-end test against a mock UrBackup server (no real server needed)
python tests/test_mock_server.py
```
## License
Released under the [GNU General Public License v3.0](LICENSE), matching the
license of [UrBackup](https://www.urbackup.org) itself. This project is a
standalone client of the UrBackup web API (it contains no UrBackup source
code); the GPL-3.0 license is applied voluntarily for consistency.
## Notes
- The API is form-encoded `POST x?a=<action>` with a `ses` session token; login is a
two-step salt/hash exchange (documented in `docs/api-reference.md`).
- Image backup IDs are positive in the API; file restore requires the client to be online.
- Session expiry is handled automatically with a single re-login retry.
- The `streamable-http` transport enforces the Bearer token on **all** requests;
keep the token long and random, and consider TLS (reverse proxy) for anything
beyond a trusted LAN.
TDQS
Scored across 31 tools
Most tools map to a clear resource+action pair (restore_files vs restore_image, archive vs unarchive vs delete, start_backup vs stop_process). The only real collision is urbackup_get_logs (list logs) versus urbackup_get_log (fetch entries of a log), plus a softer overlap between urbackup_status, urbackup_status_check and urbackup_progress, but descriptions make the intent separable.
All names share the urbackup_ prefix and snake_case, and the dominant pattern is verb_noun (get_general_settings, save_client_settings, create_user, remove_user, delete_backup). The deviations are noun-only names such as urbackup_status, urbackup_progress, urbackup_status_check, urbackup_usage_stats and urbackup_usage_graph, which break the pattern but remain readable.
31 tools is on the heavy side, and the surface can feel crowded across settings, users, stats, monitoring and restore paths. However, UrBackup is a full backup-server administration API and nearly every tool covers a distinct administrative operation, so the count is defensible rather than bloated.
Coverage is strong: backup lifecycle (start/list/archive/unarchive/delete), restore (files, image, browse, downloads), settings (general, client, mail), user CRUD with rights and passwords, logs, process control, and usage stats. Notable gaps are client/group management (no create/remove client, no group-level settings even though group origin is referenced) and no way to remove or edit extra clients.