restic-mcp

An MCP server for managing restic backups. Lets AI assistants list snapshots, browse backed-up files, create backups, apply retention policies, and more — all through the Model Context Protocol.

Tools

Read-only

Tool	Description
list_snapshots	List snapshots, with optional filters by host, tags, or paths
browse_snapshot	List files and directories inside a snapshot
diff_snapshots	Show what changed between two snapshots
find_files	Search for files by name or glob pattern across snapshots
repo_stats	Repository size, file count, and deduplication statistics
check_repo	Verify repository integrity

Write

Tool	Description
create_backup	Back up files/directories with optional tags and exclusions
forget_snapshots	Remove snapshots by ID or retention policy (keep-last, keep-daily, etc.)
prune_repo	Remove unreferenced data to reclaim disk space
restore_snapshot	Restore files from a snapshot to a target directory
tag_snapshot	Add or remove tags on a snapshot
unlock_repo	Remove stale repository locks

Requirements

• Python 3.10+
• restic installed and in PATH
• uv (recommended) or pip

Installation

git clone https://github.com/mohsenil85/restic-mcp.git
cd restic-mcp
uv sync

Configuration

The server reads repository credentials from environment variables:

Variable	Description
RESTIC_REPOSITORY	Path or URL to the restic repository
RESTIC_PASSWORD	Repository password
RESTIC_PASSWORD_COMMAND	Command that prints the password (alternative to RESTIC_PASSWORD)

Every tool also accepts an optional repo parameter to override RESTIC_REPOSITORY per-call.

Usage

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "restic": {
      "command": "uv",
      "args": ["--directory", "/path/to/restic-mcp", "run", "restic-mcp"],
      "env": {
        "RESTIC_REPOSITORY": "/path/to/your/repo",
        "RESTIC_PASSWORD_COMMAND": "pass show restic"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "restic": {
      "command": "uv",
      "args": ["--directory", "/path/to/restic-mcp", "run", "restic-mcp"],
      "env": {
        "RESTIC_REPOSITORY": "/path/to/your/repo",
        "RESTIC_PASSWORD": "your-password"
      }
    }
  }
}

MCP Inspector

Test the server interactively:

RESTIC_REPOSITORY=/path/to/repo RESTIC_PASSWORD=test uv run mcp dev src/restic_mcp/server.py

Architecture

MCP Client (Claude, Cursor, etc.)
    │
    │  stdio (JSON-RPC)
    ▼
restic-mcp server (FastMCP)
    │
    │  subprocess (async)
    ▼
restic CLI  ──►  repository (local, S3, B2, SFTP, ...)

The server is a thin async wrapper around the restic CLI. It calls restic with --json where supported for structured output, falling back to text parsing otherwise. No direct repository access — all operations go through the official restic binary.

License

MIT