URBackup MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@URBackup MCP check if the backup server is online and show any running backups"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PointlessPOS UrBackup MCP
An MCP server for UrBackup — 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).
This solution was authored by a self-hosted-focused Point of Sale solution provider. This and other self-hosted solutions are provided by PointlessPOS.
Features
Area | Tools |
Status |
|
Backups |
|
Browse/restore |
|
Backup lifecycle |
|
Logs |
|
Settings |
|
Users |
|
Usage |
|
Misc |
|
Destructive operations (restore, delete, settings changes, user changes, shutdown)
require an explicit confirm=true parameter.
Related MCP server: duplicacy-mcp
Tested with
Open WebUI — both as a remote MCP server (streamable HTTP + Bearer token) and as an OpenAPI tool
Qwen 3.8 27B
Install
pip install -e .Configure
Environment variables:
Variable | Default | Description |
|
| Server URL (default ports: 55413 HTTP, 55414 HTTPS) |
| (empty) | Admin username (empty = anonymous, if the server allows) |
| (empty) | Admin password |
|
| Set |
|
|
|
|
| Bind host for |
|
| Port for |
| (empty) | Required for |
Run
urbackup-mcp
# or
python -m urbackup_mcp.serverA .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.
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>Start it:
python -m urbackup_mcp.server # → urbackup-mcp streamable-http on http://0.0.0.0:8765/mcp (Bearer auth)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.jsonandGET /mcp/openapi.json— the spec (all 31 tools)POST /tools/{name}andPOST /mcp/tools/{name}— run a tool (Bearer auth)
In Settings → Tools → Add Tool → OpenAPI use:
Field | Value |
URL |
|
Path |
|
Auth | Bearer Token → the |
(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)
# /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.targetRunning as a service (Docker)
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir .
EXPOSE 8765
CMD ["python", "-m", "urbackup_mcp.server"]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-mcpClaude Desktop (claude_desktop_config.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
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.pyLicense
Released under the GNU General Public License v3.0, matching the license of UrBackup 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 asessession token; login is a two-step salt/hash exchange (documented indocs/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-httptransport enforces the Bearer token on all requests; keep the token long and random, and consider TLS (reverse proxy) for anything beyond a trusted LAN.
Available Tools
31 toolsurbackup_add_extra_clientB
Add an extra (non-client) host to the status page, e.g. a NAS. confirm=true required.
Inputs: hostname (required), confirm. Returns: object
urbackup_archive_backupB
Archive a backup (protected from deletion). confirm=true required.
Inputs: backup_id (required), client_id (required), confirm. Returns: object
urbackup_browse_backup_filesB
Browse files inside a backup.
Args: client_id: Client ID. backup_id: Backup ID (from urbackup_list_backups). For image backups use the ID as listed in image_backups. path: Directory path to browse ("" = root). mount_image: Mount the image backup first if needed.
Inputs: backup_id (required), client_id (required), path, mount_image. Returns: object
urbackup_change_user_passwordB
Change a user's password. confirm=true required.
Inputs: user_id (required), password (required), confirm. Returns: object
urbackup_change_user_rightsB
Change a user's rights. confirm=true required.
Inputs: rights (required), user_id (required), confirm. Returns: object
urbackup_create_userB
Create a server user. rights format: "domain=right;domain=right" e.g. "all=all" or "status=all;progress=all". confirm=true required.
Inputs: name (required), rights (required), password (required), confirm. Returns: object
urbackup_delete_backupB
Delete a backup. confirm=true required.
Args: client_id: Client ID. backup_id: Backup ID. delete_now: Delete immediately instead of marking for deletion.
Inputs: backup_id (required), client_id (required), confirm, delete_now. Returns: object
urbackup_download_file_urlC
Get a session-scoped URL to download a single file from a backup.
Inputs: path (required), backup_id (required), client_id (required). Returns: object
urbackup_download_zip_urlB
Get a session-scoped URL to download a directory from a backup as a zip.
Inputs: path (required), backup_id (required), client_id (required), file_filter. Returns: object
urbackup_get_client_settingsB
Get settings for a client (backup frequencies, windows, paths, exclusions, quotas, ...). Values show the effective value plus the server/group/client origin.
Inputs: client_id (required). Returns: object
urbackup_get_general_settingsA
Get general server settings (backup folder, limits, cleanup window, speed limits, quotas, ...).
Inputs: no named parameters. Returns: object
urbackup_get_logB
Get the detailed entries of a log (from urbackup_get_logs).
Inputs: log_id (required). Returns: object
urbackup_get_logsB
List backup logs.
Args: client_ids: Filter to specific clients (empty = all). log_level: 0 = info and up, 1 = warnings and up, 2 = errors only.
Inputs: log_level, client_ids. Returns: object
urbackup_get_mail_settingsA
Get mail server settings (password is masked).
Inputs: no named parameters. Returns: object
urbackup_list_backupsB
List file and image backups for a client, newest first, with size, incremental flag, archive state and timestamps.
Inputs: client_id (required). Returns: object
urbackup_list_usersA
List server users with their rights.
Inputs: no named parameters. Returns: object
urbackup_progressA
Show running backup/restore processes with progress, speed, ETA, and (optionally) the most recent completed activities.
Inputs: include_last_activities. Returns: object
urbackup_remove_userA
Remove a server user. confirm=true required.
Inputs: user_id (required), confirm. Returns: object
urbackup_restore_filesB
Restore files from a backup to the client (client must be online).
Args: client_id: Client ID. backup_id: Backup ID to restore from. path: Path of the file or directory inside the backup to restore. file_filter: Optional glob filter for files (e.g. "*.docx"). confirm: Must be true to actually perform the restore.
Inputs: path (required), backup_id (required), client_id (required), confirm, +1 more. Returns: object
urbackup_restore_imageA
Start an image (disk) restore. Returns a restore token and authkey that the restore client needs.
Args: backup_id: Image backup ID (from image_backups in urbackup_list_backups). confirm: Must be true to actually start the restore.
Inputs: backup_id (required), confirm. Returns: object
urbackup_save_client_settingsA
Update settings for a client. Only pass the keys to change. confirm=true required. Examples: {"default_dirs": "C:\Users|User files"} {"update_freq_incr": 14400} {"exclude_files": ".mp3;.avi"}
Inputs: settings (required), client_id (required), confirm. Returns: object
urbackup_save_general_settingsA
Update general server settings. Only pass the keys to change. confirm=true required. See urbackup_get_general_settings for current values.
Inputs: settings (required), confirm. Returns: object
urbackup_save_mail_settingsB
Update mail server settings. Pass testmailaddr to send a test mail. confirm=true required.
Inputs: settings (required), confirm, testmailaddr. Returns: object
urbackup_shutdownB
Shut down the UrBackup server. confirm=true required.
Inputs: confirm. Returns: object
urbackup_start_backupB
Start a backup for one or more clients.
Args: client_ids: Client IDs (from urbackup_status). backup_type: One of incr_file, full_file, incr_image, full_image.
Inputs: client_ids (required), backup_type (required). Returns: object
urbackup_statusB
List all UrBackup clients with online state, last backup times, OS, version, and running processes. Also returns server-level flags (disk space problems, database errors, image/file backup availability).
Inputs: no named parameters. Returns: object
urbackup_status_checkA
Run the server's health check for all clients (connectivity, settings, backup state) and return the results.
Inputs: no named parameters. Returns: object
urbackup_stop_processB
Stop a running backup/restore process.
Args: client_id: Client ID the process belongs to. process_id: Process ID from urbackup_progress.
Inputs: client_id (required), process_id (required). Returns: object
urbackup_unarchive_backupC
Remove archive protection from a backup. confirm=true required.
Inputs: backup_id (required), client_id (required), confirm. Returns: object
urbackup_usage_graphC
Storage usage over time.
Args: scale: d = daily, m = monthly, y = yearly. client_id: Optional client to filter by.
Inputs: scale, client_id. Returns: object
urbackup_usage_statsB
Storage usage per client (file + image bytes used).
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
SSH client, server management and one remote MCP URL for your machines, with human approvals.
1MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
A paid remote MCP for CLI tool MCP, built to return verdicts, receipts, usage logs, and audit-ready
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceMCP server that exposes the Cove Data Protection (N-able Backup) Management Service JSON-RPC API as 247 tools for managing backup, recovery, and partner/account operations.-
- AlicenseAqualityDmaintenanceMCP server for administering Duplicacy backups via the duplicacy-web API, enabling AI clients to inspect and manage storages, repositories, schedules, and jobs.15MIT
- AlicenseNot gradedqualityBmaintenanceA typed MCP server for curated backup administration of DBackup via its API, exposing tools for backup jobs, execution history, notifications, storage, and bounded restore workflows.MIT
- AlicenseAqualityCmaintenanceConnects MCP clients to a self-hosted photo library through its REST API, exposing assets, albums, people, search, and optional administrative toolsets with read-only defaults and confirm-gated writes. It supports stdio and localhost Streamable HTTP transports.587 npmMIT