Duplicati MCP

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:

# 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:

{

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

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

docker compose up -d

With Docker Compose (local build)

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

docker compose up -d --build

Direct Docker usage

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

# 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:

{

"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:

{

"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

{

"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

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

Status & Progress

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

Configuration

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

History & Diagnostics (SQLite — requires DUPLICATI_DB_PATH)

1. db_get_backup_metadata — Rich metadata from the local database: last run date, duration, file counts, quota usage, last error
2. db_get_backup_schedule — Schedule configuration for a backup job
3. db_list_errors — Recent error log entries, optionally filtered by job
4. db_list_notifications — System notifications (update alerts, etc.)
5. db_get_backup_options — Configuration options for a job (compression, retention policy, etc.) — passphrases excluded
6. db_list_operations — Operation history for a job (Backup, Restore, List, etc.) with timestamps
7. db_get_operation_log — Full result and statistics for a specific operation
8. 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

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:

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:

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

docker pull kcofoni/duplicati-mcp:latest

Development

File Structure

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

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

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

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.