Zsnoop MCP
Use zsnoop-mcp for ZFS snapshot exploration and recovery. The plugin wires the
upstream stdio MCP server as uvx zsnoop-mcp; the server reads hosts from
$ZSNOOP_CONFIG, $XDG_CONFIG_HOME/zsnoop-mcp/hosts.toml, or
~/.config/zsnoop-mcp/hosts.toml.
First Steps
- Call
list_hosts before host-specific work.
- For health or inventory questions, call
list_pools, pool_status, then
list_datasets or list_snapshots.
- For file recovery, narrow by host, dataset, path, and time window before
reading or fetching content.
- For restore requests, confirm the user wants to write to the live server and
verify the host has
allow_restore = true plus a non-empty restore_paths
allowlist. Restore tools are the only mutating zsnoop tools.
Workflow Map
- Pool health:
list_pools -> pool_status.
- Snapshot coverage:
list_snapshots -> snapshot_cadence.
- What changed:
diff_snapshots, file_diff, versions_of, or
file_history.
- Find deleted or missing files:
snapshots_containing, last_appearance,
find_deleted.
- Inspect content:
list_dir, read_file, find_files, content_grep,
checksum_file.
- Copy out to this workstation:
fetch_file or fetch_dir.
- Restore on the ZFS host:
restore_file or restore_dir only after explicit
confirmation and allowlist verification.
Read references/tools.md for detailed tool selection, limits, and path
rules. Read references/configuration.md when setting up or debugging
hosts.toml, SSH, sudo mode, local transport, or restore allowlists.
Guardrails
- Treat snapshot paths as relative to the snapshot root; leading
/ is okay,
but .. is rejected.
- Prefer bounded searches with
after, before, dataset, and
max_results instead of broad unfiltered calls.
- Do not ask zsnoop to delete snapshots, destroy datasets, mount filesystems, or
change pools; it does not expose those operations.
- Do not use restore tools unless the user explicitly asks to restore to the
live host. For safer recovery, prefer
fetch_file/fetch_dir to a local path.
- For root-owned files, expect host config to require
sudo = true and
passwordless sudo on the remote.
1---2name: zsnoop-mcp3description: Use for ZFS snapshot exploration and recovery through zsnoop-mcp. Triggers include "restore a file from a ZFS snapshot", "when did this file get deleted", "check my zpool health", "compare two snapshots", "grep inside a snapshot", "show snapshot cadence", "list ZFS pools/datasets/snapshots", "find when a file appeared or changed", "fetch a file out of a snapshot to my workstation", and "read a file inside a snapshot". Also use when configuring or troubleshooting the zsnoop MCP server, hosts.toml, SSH or local transport, sudo mode, or restore allowlists.4---56# Zsnoop MCP78Use `zsnoop-mcp` for ZFS snapshot exploration and recovery. The plugin wires the9upstream stdio MCP server as `uvx zsnoop-mcp`; the server reads hosts from10`$ZSNOOP_CONFIG`, `$XDG_CONFIG_HOME/zsnoop-mcp/hosts.toml`, or11`~/.config/zsnoop-mcp/hosts.toml`.1213## First Steps14151. Call `list_hosts` before host-specific work.162. For health or inventory questions, call `list_pools`, `pool_status`, then17 `list_datasets` or `list_snapshots`.183. For file recovery, narrow by host, dataset, path, and time window before19 reading or fetching content.204. For restore requests, confirm the user wants to write to the live server and21 verify the host has `allow_restore = true` plus a non-empty `restore_paths`22 allowlist. Restore tools are the only mutating zsnoop tools.2324## Workflow Map2526- Pool health: `list_pools` -> `pool_status`.27- Snapshot coverage: `list_snapshots` -> `snapshot_cadence`.28- What changed: `diff_snapshots`, `file_diff`, `versions_of`, or29 `file_history`.30- Find deleted or missing files: `snapshots_containing`, `last_appearance`,31 `find_deleted`.32- Inspect content: `list_dir`, `read_file`, `find_files`, `content_grep`,33 `checksum_file`.34- Copy out to this workstation: `fetch_file` or `fetch_dir`.35- Restore on the ZFS host: `restore_file` or `restore_dir` only after explicit36 confirmation and allowlist verification.3738Read `references/tools.md` for detailed tool selection, limits, and path39rules. Read `references/configuration.md` when setting up or debugging40`hosts.toml`, SSH, sudo mode, local transport, or restore allowlists.4142## Guardrails4344- Treat snapshot paths as relative to the snapshot root; leading `/` is okay,45 but `..` is rejected.46- Prefer bounded searches with `after`, `before`, `dataset`, and47 `max_results` instead of broad unfiltered calls.48- Do not ask zsnoop to delete snapshots, destroy datasets, mount filesystems, or49 change pools; it does not expose those operations.50- Do not use restore tools unless the user explicitly asks to restore to the51 live host. For safer recovery, prefer `fetch_file`/`fetch_dir` to a local path.52- For root-owned files, expect host config to require `sudo = true` and53 passwordless sudo on the remote.
dinglebear-ai