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.

Quickstart

# 1. Install
uv tool install zsnoop-mcp

# 2. Configure one host (more in docs/INSTALL.md)
mkdir -p ~/.config/zsnoop-mcp
cat > ~/.config/zsnoop-mcp/hosts.toml ` 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](https://github.com/hamsolodev/zsnoop-mcp/blob/main/docs/USAGE.md) for example prompts that exercise the
file-recovery, drift-audit, and forensics workflows.

## Documentation

- **New here?** Start with the [onboarding tutorial](https://github.com/hamsolodev/zsnoop-mcp/blob/main/docs/onboarding/index.md) —
  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](https://github.com/hamsolodev/zsnoop-mcp/blob/main/docs/INSTALL.md) — local setup, ZFS delegation, sudo mode
- [Usage examples](https://github.com/hamsolodev/zsnoop-mcp/blob/main/docs/USAGE.md) — concrete prompts the tools handle
- [Security model](https://github.com/hamsolodev/zsnoop-mcp/blob/main/docs/SECURITY.md) — threat model, guarantees, sudo tradeoff
- [Publishing](https://github.com/hamsolodev/zsnoop-mcp/blob/main/docs/PUBLISHING.md) — 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](https://github.com/hamsolodev/zsnoop-mcp/blob/main/LICENSE).