duplicati-mcp

Duplicati MCP 服务

用于通过大模型管理 Duplicati 备份的 MCP（Model Context Protocol）服务。

Version française / 法语版本

架构

该服务封装了 Duplicati REST API，并通过 MCP 协议提供其功能。支持两种传输方式：

• stdio — 通过 Claude Code 在本地使用（无需网络，也无需端口）
• Streamable HTTP — 用于 Docker 部署，可通过网络访问

入门

使用 Claude Code 在本地运行（stdio）

最简单的入门方式。项目根目录中的 .mcp.json 会处理所有配置：

# Install uv if needed
brew install uv

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

在 .mcp.json 中设置你的 Duplicati URL 和密码：

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

使用 Docker Compose（Docker Hub 镜像）

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

使用 Docker Compose（本地构建）

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

直接使用 Docker

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

验证

# 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"}}}'

客户端配置

Claude Code — 本地（stdio）

如需在本地使用且不通过 Docker，请在项目的 .mcp.json 中添加：

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

凭据从项目根目录的 .env 文件中加载（参见入门）。

Claude Code — Docker/远程（HTTP）

在 .mcp.json 中添加：

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

Claude Desktop

Claude Desktop 需要使用 mcp-proxy 作为连接 HTTP 服务的桥接工具。在配置文件中添加：

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"]
    }
  }
}

可用工具

连接后，大模型可以使用以下工具：

备份作业

1. list_backups — 列出所有已配置的作业，包括 ID、名称、上次运行日期和结果
2. get_backup — 获取特定作业的详细信息
3. run_backup — 立即触发备份作业
4. abort_backup — 中止作业当前正在运行的备份

状态与进度

5. get_progress — 获取活动备份任务的实时进度（阶段、百分比、文件数量）
6. get_server_status — 获取 Duplicati 服务状态、版本和活动任务

配置

7. export_backup_config — 将作业配置导出为 JSON
8. update_backup_config — 原地更新现有作业配置（可与 export_backup_config 配合使用，以修改来源、设置、计划等）
9. import_backup_config — 从 JSON 导入作业配置（创建新作业）

历史记录与诊断（SQLite — 需要 DUPLICATI_DB_PATH）

10. db_get_backup_metadata — 从本地数据库获取丰富的元数据：上次运行日期、持续时间、文件数量、配额使用情况、上次错误
11. db_get_backup_schedule — 获取备份作业的计划配置
12. db_list_errors — 列出最近的错误日志条目，可按作业筛选
13. db_list_notifications — 列出系统通知（更新提醒等）
14. db_get_backup_options — 获取作业的配置选项（压缩、保留策略等）——不包含密码短语
15. db_list_operations — 列出作业的操作历史记录（Backup、Restore、List 等），包括时间戳
16. db_get_operation_log — 获取特定操作的完整结果和统计信息
17. db_list_filesets — 列出作业可用的还原点（备份版本）

示例提示词

将服务连接到大模型后，可以使用以下提示词：

常规状态

• “我的 Duplicati 配置了哪些备份作业？”
• “最近一次运行的备份是什么？结果如何？”
• “当前是否有备份正在运行？”

历史记录与统计 (需要 DUPLICATI_DB_PATH)

• “显示备份作业 2 最近的 10 次操作”
• “近期备份的平均耗时是多少？”
• “过去几周我的备份是否出现过错误？”
• “已备份多少个文件？目标位置上的总大小是多少？”

还原点 (需要 DUPLICATI_DB_PATH)

• “我的备份作业有哪些可用的还原点？”
• “可用于还原的最早备份是什么时候？”

配置 (需要 DUPLICATI_DB_PATH)

• “我的备份作业配置了什么保留策略？”
• “正在使用哪些压缩和加密选项？”

诊断 (需要 DUPLICATI_DB_PATH)

• “Duplicati 中是否有待处理的系统通知？”
• “我的 Duplicati 最近是否遇到错误？有哪些错误？”
• “分析最近一次备份，并告诉我是否一切正常”

开放式 (组合多个工具)

• “全面检查我的 Duplicati 备份并生成健康报告”

环境变量

变量	默认值	描述
DUPLICATI_URL	http://localhost:8200	Duplicati 实例的 URL
DUPLICATI_PASSWORD	(empty)	Duplicati Web 界面密码（未设置密码时留空）
DUPLICATI_READONLY	(empty)	设置为 true、1 或 yes 以禁用写入操作
DUPLICATI_DB_PATH	(empty)	Duplicati-server.sqlite 的路径 — 启用由 SQLite 提供支持的历史记录工具
MCP_TRANSPORT	stdio	传输方式：stdio 或 streamable-http
MCP_PORT	3000	Streamable HTTP 传输的端口

只读模式

DUPLICATI_READONLY=true 会禁用 run_backup、abort_backup、update_backup_config 和 import_backup_config。所有读取工具仍保持启用。适用于安全地查看和分析备份配置，而无需承担任何修改风险。

SQLite 访问

设置 DUPLICATI_DB_PATH 可启用 db_* 工具，这些工具直接从 Duplicati SQLite 数据库读取数据。访问严格为只读：数据库会以只读模式打开，并在执行任何查询前通过 SQLite Online Backup API 复制到内存中 — 不会锁定或修改正在使用的 Duplicati 数据库。

本地使用 — 指向计算机上的服务器数据库：

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

Docker — 将 Duplicati 配置目录作为只读卷共享。在 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

• 仓库：kcofoni/duplicati-mcp
• 最新标签：kcofoni/duplicati-mcp:latest

docker pull kcofoni/duplicati-mcp:latest

开发

文件结构

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

运行测试

# 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

交互式工具测试（本地）

uv run mcp dev src/duplicati_mcp/server.py

故障排除

无法连接到 Duplicati

检查容器是否能够访问 DUPLICATI_URL。如果两者都在 Docker 中运行，请将它们放在同一网络中，并使用服务名称作为主机名。

身份验证失败

确认 DUPLICATI_PASSWORD 与 Duplicati Web 界面中设置的密码一致。未配置密码时留空。

MCP 端点无响应

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

许可证

本项目采用 MIT 许可证 — 详情请参阅 LICENSE 文件。