io.github.kcofoni/duplicati-mcp

Official

by kcofoni · Python

MCP server for Duplicati backup management — list, run, monitor and configure jobs from an LLM.

Manages Duplicati backup jobs—list, run, monitor and configure backups via AI agents.

README.md10 KBView on GitHub

Duplicati MCP Server

MCP (Model Context Protocol) server for managing Duplicati backups from an LLM.

Version française / French version

Architecture

The server wraps the Duplicati REST API and exposes it via the MCP protocol. Two transports are supported:

stdio — for local use via Claude Code (no network, no port)
Streamable HTTP — for Docker deployment, accessible over the network

Getting Started

Local use with Claude Code (stdio)

The simplest way to get started. The .mcp.json at the project root handles everything:

bash

# Install uv if needed
brew install uv

# Claude Code will auto-detect .mcp.json and launch the server

Set your Duplicati URL and password in .mcp.json:

json

{
  "mcpServers": {
    "duplicati": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "duplicati-mcp"],
      "env": {
        "DUPLICATI_URL": "http://localhost:8200",
        "DUPLICATI_PASSWORD": "your-password",
        "DUPLICATI_READONLY": ""
      }
    }
  }
}

With Docker Compose (Docker Hub image)

bash

# Edit DUPLICATI_URL and DUPLICATI_PASSWORD in docker-compose.yml, then:
docker compose up -d

With Docker Compose (local build)

bash

# Edit docker-compose.yml: comment out `image:` and uncomment `build: .`
docker compose up -d --build

Direct Docker usage

bash

docker run -d \
  --name duplicati-mcp-server \
  -p 3000:3000 \
  -e DUPLICATI_URL=http://your-duplicati-host:8200 \
  -e DUPLICATI_PASSWORD=your-password \
  kcofoni/duplicati-mcp:latest

Verification

bash

# Check that the server is running
docker logs duplicati-mcp-server

# Test the MCP endpoint
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Client Configuration

Claude Code — local (stdio)

For local use without Docker, add to your project .mcp.json:

json

{
  "mcpServers": {
    "duplicati": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "duplicati-mcp"],
      "env": {
        "DUPLICATI_URL": "http://localhost:8200",
        "DUPLICATI_READONLY": ""
      }
    }
  }
}

Credentials are loaded from the .env file at the project root (see Getting Started).

Claude Code — Docker/remote (HTTP)

Add to your .mcp.json:

json

{
  "mcpServers": {
    "duplicati": {
      "type": "http",
      "url": "http://your-host:3000/mcp"
    }
  }
}

Claude Desktop

Claude Desktop requires mcp-proxy as a bridge to HTTP servers. Add to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "duplicati": {
      "command": "uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "http://your-host:3000/mcp"]
    }
  }
}

Available Tools

Once connected, the LLM has access to:

Backup Jobs

list_backups — List all configured jobs with ID, name, last run date and result
get_backup — Get detailed information about a specific job
run_backup — Trigger a backup job immediately
abort_backup — Abort the currently running backup for a job

Status & Progress

get_progress — Live progress of the active backup task (phase, %, file counts)
get_server_status — Duplicati server state, version and active task

Configuration

export_backup_config — Export a job configuration as JSON
update_backup_config — Update an existing job configuration in place (use with export_backup_config to modify sources, settings, schedule, etc.)
import_backup_config — Import a job configuration from JSON (creates a new job)

History & Diagnostics (SQLite — requires `DUPLICATI_DB_PATH`)

db_get_backup_metadata — Rich metadata from the local database: last run date, duration, file counts, quota usage, last error
db_get_backup_schedule — Schedule configuration for a backup job
db_list_errors — Recent error log entries, optionally filtered by job
db_list_notifications — System notifications (update alerts, etc.)
db_get_backup_options — Configuration options for a job (compression, retention policy, etc.) — passphrases excluded
db_list_operations — Operation history for a job (Backup, Restore, List, etc.) with timestamps
db_get_operation_log — Full result and statistics for a specific operation
db_list_filesets — Available restore points (backup versions) for a job

Example Prompts

Once the server is connected to your LLM, here are prompts you can use:

General status

"What backup jobs are configured on my Duplicati?"
"What was the last backup that ran and what was the result?"
"Is a backup currently running?"

History & statistics (requires DUPLICATI_DB_PATH)

"Show me the last 10 operations for backup job 2"
"What is the average duration of recent backups?"
"Have there been any errors on my backups in the past few weeks?"
"How many files are backed up and what is the total size on the destination?"

Restore points (requires DUPLICATI_DB_PATH)

"What restore points are available for my backup job?"
"What is the oldest backup available for a restore?"

Configuration (requires DUPLICATI_DB_PATH)

"What retention policy is configured on my backup job?"
"What compression and encryption options are in use?"

Diagnostics (requires DUPLICATI_DB_PATH)

"Are there any pending system notifications on Duplicati?"
"Has my Duplicati encountered any errors recently? Which ones?"
"Analyse the last backup and tell me if everything went well"

Open-ended (combines multiple tools)

"Give me a full health report on my Duplicati backups"

Environment Variables

Variable	Default	Description
`DUPLICATI_URL`	`http://localhost:8200`	URL of the Duplicati instance
`DUPLICATI_PASSWORD`	(empty)	Duplicati web interface password (leave empty if none set)
`DUPLICATI_READONLY`	(empty)	Set to `true`, `1` or `yes` to disable write operations
`DUPLICATI_DB_PATH`	(empty)	Path to `Duplicati-server.sqlite` — enables SQLite-backed history tools
`MCP_TRANSPORT`	`stdio`	Transport: `stdio` or `streamable-http`
`MCP_PORT`	`3000`	Port for Streamable HTTP transport

Read-only Mode

DUPLICATI_READONLY=true disables run_backup, abort_backup, update_backup_config and import_backup_config. All read tools remain active. Useful for safely exploring and analysing backup configurations without any risk of modification.

SQLite Access

Setting DUPLICATI_DB_PATH enables the db_* tools, which read directly from the Duplicati SQLite databases. Access is strictly read-only: databases are opened in read-only mode and copied to memory via the SQLite Online Backup API before any query — the live Duplicati databases are never locked or modified.

Local use — point to the server database on your machine:

code

DUPLICATI_DB_PATH=/path/to/duplicati/config/Duplicati-server.sqlite

Docker — share the Duplicati config directory as a read-only volume. In docker-compose.yml:

yaml

services:
  duplicati-mcp:
    # ...
    volumes:
      - duplicati_config:/duplicati-config:ro   # named volume (recommended)
      # or: - /srv/duplicati/config:/duplicati-config:ro  # bind mount
    environment:
      - DUPLICATI_DB_PATH=/duplicati-config/Duplicati-server.sqlite

volumes:
  duplicati_config:   # must be the same volume used by the Duplicati container

Docker Hub

Repository: kcofoni/duplicati-mcp
Latest tag: kcofoni/duplicati-mcp:latest

bash

docker pull kcofoni/duplicati-mcp:latest

Development

File Structure

code

duplicati-mcp/
├── src/
│   └── duplicati_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── client.py        # Duplicati REST API client
│       ├── db.py            # Read-only SQLite access (server DB + per-backup DBs)
│       └── server.py        # FastMCP server and tools
├── mcp-publication/         # MCP registry publication files
├── requirements.txt         # Python dependencies
├── pyproject.toml           # Project metadata
├── Dockerfile
├── docker-compose.yml
├── .mcp.json                # Claude Code local config (stdio)
├── test_server.sh           # Docker container smoke test
├── test_mcp.py              # MCP protocol test
├── README.md                # This file (English)
└── README_fr.md             # French documentation

Running Tests

bash

# Smoke test (requires running Docker container)
./test_server.sh

# MCP protocol test (requires running server)
python test_mcp.py
python test_mcp.py localhost:3000

Interactive Tool Testing (local)

bash

uv run mcp dev src/duplicati_mcp/server.py

Troubleshooting

Cannot connect to Duplicati

Check that DUPLICATI_URL is reachable from the container. If both run in Docker, put them on the same network and use the service name as hostname.

Authentication failed

Verify DUPLICATI_PASSWORD matches the password set in Duplicati's web interface. Leave empty if no password is configured.

MCP endpoint not responding

bash

docker ps | grep duplicati-mcp-server
docker logs duplicati-mcp-server

License

This project is licensed under the MIT License — see the LICENSE file for details.

Install

Configuration

Environment variables

DUPLICATI_URLrequired

URL of the Duplicati instance (e.g. http://localhost:8200)

DUPLICATI_PASSWORDsecret

Duplicati web interface password (leave empty if none configured)

DUPLICATI_READONLY

Set to true to disable write operations (run, abort, update, import). Default: false

DUPLICATI_DB_PATH

Path to Duplicati-server.sqlite — enables SQLite history tools (db_*). Leave empty to disable.

claude_desktop_config.json

{
  "mcpServers": {
    "duplicati-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/kcofoni/duplicati-mcp:v1.1.1"
      ],
      "env": {
        "DUPLICATI_URL": "<YOUR_DUPLICATI_URL>",
        "DUPLICATI_PASSWORD": "<YOUR_DUPLICATI_PASSWORD>",
        "DUPLICATI_READONLY": "<YOUR_DUPLICATI_READONLY>",
        "DUPLICATI_DB_PATH": "<YOUR_DUPLICATI_DB_PATH>"
      }
    }
  }
}

Duplicati MCP Server

Architecture

Getting Started

Local use with Claude Code (stdio)

With Docker Compose (Docker Hub image)

With Docker Compose (local build)

Direct Docker usage

Verification

Client Configuration

Claude Code — local (stdio)

Claude Code — Docker/remote (HTTP)

Claude Desktop

Available Tools

Backup Jobs

Status & Progress

Configuration

History & Diagnostics (SQLite — requires DUPLICATI_DB_PATH)

Example Prompts

Environment Variables

Read-only Mode

SQLite Access

Docker Hub

Development

File Structure

Running Tests

Interactive Tool Testing (local)

Troubleshooting

Cannot connect to Duplicati

Authentication failed

MCP endpoint not responding

License

Install

Configuration

History & Diagnostics (SQLite — requires `DUPLICATI_DB_PATH`)