Skip to main content
Glama
URBackup MCP
by MarkPhsd

PointlessPOS UrBackup MCP

License: GPL-3.0

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

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.

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

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

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:

    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'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)

# /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)

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-mcp

Claude 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.py

License

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 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.

Available Tools

31 tools
urbackup_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

    B3.3/5.0

    Scored across 31 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for administering Duplicacy backups via the duplicacy-web API, enabling AI clients to inspect and manage storages, repositories, schedules, and jobs.
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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
    • A
      license
      A
      quality
      C
      maintenance
      Connects 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.
      5
      87 npm
      MIT