zsnoop-mcp

Ask your AI assistant things like:

• ⏪ "Recover my .zshrc from before I committed the rewrite three weeks ago."
• 🧹 "Which snapshots older than 6 months are wasting the most space?"
• 🔎 "When did the directory /srv/backups first appear on this host?"
• ⌛ "Find everything deleted under /home/youruser in the last week, and show me when each thing was last present."
• 🏥 "Are any of my pools throwing disk errors? When was the last scrub?"

An MCP server for ZFS snapshot exploration and recovery on remote hosts — read-only by default, with opt-in restore_* tools (v0.4.0+) gated per host.

Browse, diff, search, and read files from any snapshot on any of your ZFS hosts through your AI assistant, over a single persistent SSH connection per host. Read-only by default; the writable restore_file / restore_dir tools (v0.4.0+) are opt-in per host and bounded by an operator-defined path allowlist — with the stock config, nothing on the remote can be written.

About this codebase

This project was developed collaboratively with Claude Code (Anthropic). The human author (Mark Hellewell) defined the architecture, security model, and acceptance criteria, and reviewed every change before it landed; Claude handled the bulk of the drafting, test scaffolding, refactors, and documentation. Read-only-by-default was a hard requirement from day one, enforced by an explicit method allowlist and the test suite. The opt-in restore_* tools added in v0.4.0 are the only writable methods and are gated server-side on per-host config (off by default; requires a non-empty path allowlist when enabled) — see SECURITY.md. If you're reviewing or auditing the code, treat that as context, not as a reason to skip the usual scrutiny.

How it works

┌─────────────────┐   MCP (stdio)    ┌────────────────────┐
│   MCP client    │ ───────────────► │  zsnoop-mcp server │
│ (Claude Code,…) │ ◄─────────────── │     (local)        │
└─────────────────┘                  └──────────┬─────────┘
                                                │
                       JSON-RPC over SSH stdio  │  one persistent
                       (one channel per host)   │  subprocess
                                                ▼
                                      ┌─────────────────────┐
                                      │  zfs-snoop-agent    │
                                      │  (remote, Python)   │
                                      └─────────┬───────────┘
                                                │
                                       zfs list / zfs diff,
                                       walk .zfs/snapshot/…
                                                ▼
                                            ZFS pool

The remote agent is a single-file, stdlib-only Python script. It can be pre-installed at ~/bin/zfs-snoop-agent on each host, or streamed over SSH stdin on each connection — no permanent install required.

Tools exposed to the LLM

Designed around four dominant workflows: file recovery ("get me /etc/foo as it was yesterday" — to your workstation, or restored in place on the server), config drift audit ("when did X change?"), forensics ("what was on the box when Y broke?"), and storage housekeeping ("which snapshots are biggest / oldest?"). The tools are grouped below by their dominant use case; many compose across workflows.

Discovery & introspection

Snapshot inventory & housekeeping

Browsing & sizing within a snapshot

Reading content

Comparing snapshots & tracing change

Recovery — copy out to your workstation

Recovery — restore in place on the server (opt-in, v0.4.0+)

These are the only writable tools. Disabled per host by default; require allow_restore = true and a non-empty restore_paths allowlist in hosts.toml. See SECURITY.md for the threat model.

Time-range parameters accept ISO 8601 or human phrases — yesterday, last week, 3 days ago, 2 hours ago, etc. Parsing happens locally; the agent only sees absolute ISO 8601 timestamps.

Configure

Create ~/.config/zsnoop-mcp/hosts.toml:

[hosts.r2d2]
ssh_target = "r2d2.example.com"
agent_mode = "bootstrap"          # or "preinstalled"
sudo       = false                # set true to read root-owned snapshot files
pools      = ["rpool", "bpool"]   # used by the LLM for scoping hints

[hosts.c3po]
ssh_target = "c3po.example.com"
agent_mode = "bootstrap"
sudo       = false
pools      = ["rpool"]

[hosts.this-box]
transport  = "local"              # run the agent on this machine, no SSH
agent_mode = "bootstrap"

Per-host setup on the remote (one-time):

# user mode: grant diff for each pool you want to compare snapshots in
sudo zfs allow -u $USER diff rpool

See docs/INSTALL.md for the full setup, including sudo mode for reading root-owned snapshot files.

Wire into Claude Code

After uv tool install zsnoop-mcp:

claude mcp add zsnoop --scope user -- zsnoop-mcp

That writes the entry directly to your Claude Code config; no JSON editing needed. Restart your Claude Code session; the tools appear under the zsnoop namespace.

If you're running from a worktree instead of an installed binary, point the command at uv run --directory <path> instead:

claude mcp add zsnoop --scope user -- \
    uv run --directory ~/path/to/zsnoop-mcp zsnoop-mcp

Or, if you'd rather edit ~/.claude/settings.json by hand:

{
  "mcpServers": {
    "zsnoop": { "command": "zsnoop-mcp" }
  }
}

Use

See docs/USAGE.md for example prompts that exercise the file-recovery, drift-audit, and forensics workflows.

Documentation

• New here? Start with the onboarding tutorial — a 10-chapter, what/why/how walk through the codebase, ending with a worked example of adding a new tool end-to-end. Renders nicely as HTML via uv run mkdocs serve (see --group docs).
• Installation — local setup, ZFS delegation, sudo mode
• Usage examples — concrete prompts the tools handle
• Security model — threat model, guarantees, sudo tradeoff
• Publishing — releasing to PyPI

Development

uv sync                            # install runtime + dev deps into .venv
uv run pytest                      # tests
uv run ruff check                  # lint
uv run ruff format                 # format
uv run mypy                        # type-check
uv run pip-audit --skip-editable   # CVE scan of locked deps
uv run pre-commit install          # set up hooks

Pre-commit runs pip-audit automatically whenever pyproject.toml or uv.lock change.

License

MIT — see LICENSE.

Quickstart

# 1. Install
uv tool install zsnoop-mcp        # or: pipx install zsnoop-mcp

# 2. Configure one host (more in docs/INSTALL.md)
mkdir -p ~/.config/zsnoop-mcp
cat > ~/.config/zsnoop-mcp/hosts.toml <<'EOF'
[hosts.myhost]
ssh_target = "myhost.example.com"
agent_mode = "bootstrap"
sudo       = false
EOF

# 3. Register the MCP server with Claude Code
claude mcp add zsnoop --scope user -- zsnoop-mcp

# 4. Restart Claude Code, then ask your assistant any of the prompts above.

The agent is streamed over SSH on first connect — nothing needs to be installed on the remote host beyond python3 (3.11+) and the zfs CLI. Read-only by default, enforced by an explicit allowlist on the agent side. The writable restore_file / restore_dir tools (v0.4.0+) are opt-in per host and bounded by an operator-defined path allowlist; with the default config they refuse before doing anything.

Install

From PyPI (recommended)

uv tool install zsnoop-mcp    # or: pipx install zsnoop-mcp / pip install zsnoop-mcp

Run it with zsnoop-mcp.

From a clone (for hacking on the code)

git clone https://github.com/hamsolodev/zsnoop-mcp.git
cd zsnoop-mcp
uv sync

Run it with uv run zsnoop-mcp from the checkout.

See docs/PUBLISHING.md for the per-release flow (version bump → tag → CI publishes via OIDC).