# restic-mcp

An [MCP](https://modelcontextprotocol.io) server for managing [restic](https://restic.net) 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](https://restic.readthedocs.io/en/stable/020_installation.html) installed and in PATH
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```bash
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`:

```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):

```json
{
  "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:

```bash
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