Zsnoop
About
An MCP server for read-only exploration of ZFS snapshots on remote hosts.
Details
- Author
- hamsolodev
- Categories
- File Management, Other, Infrastructure
Jump to
Setup
Install Zsnoop in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/hamsolodev/zsnoop-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
- ⏪"Recover my.zshrcfrom before I committed the rewrite three weeks ago."
- 🧹"Which snapshots older than 6 months are wasting the most space?"
- 🔎"When did the directory/srv/backupsfirst appear on this host?"
- ⌛"Find everything deleted under/home/youruserin 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 forZFS snapshot exploration and recovery on remote hosts— read-only by default, with opt-inrestore_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 writablerestore_file/restore_dirtools (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.
# 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 <<'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 beyondpython3(3.11+) and thezfsCLI.Read-only by default, enforced by an explicit allowlist on the agent side. The writablerestore_file/restore_dirtools (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.
This project was developed collaboratively withClaude 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-inrestore_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) — seeSECURITY.md. If you're reviewing or auditing the code, treat that as context, not as a reason to skip the usual scrutiny.
┌─────────────────┐ 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-agenton each host, or streamed over SSH stdin on each connection — no permanent install required.
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?"), andstorage housekeeping("which snapshots are biggest / oldest?"). The tools are grouped below by their dominant use case; many compose across workflows.
Comparing snapshots & tracing change
Recovery — restore in place on the server (opt-in, v0.4.0+)
These are the onlywritabletools. Disabled per host by default; requireallow_restore = trueand a non-emptyrestore_pathsallowlist inhosts.toml. SeeSECURITY.mdfor the threat model.
Time-range parameters accept ISO 8601orhuman phrases —yesterday,last week,3 days ago,2 hours ago, etc. Parsing happens locally; the agent only sees absolute ISO 8601 timestamps.
git clone https://github.com/hamsolodev/zsnoop-mcp.git cd zsnoop-mcp uv sync
Run it withuv run zsnoop-mcpfrom the checkout.
Seedocs/PUBLISHING.mdfor the per-release flow (version bump → tag → CI publishes via OIDC).
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
Seedocs/INSTALL.mdfor the full setup, including sudo mode for reading root-owned snapshot files.
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 thezsnoopnamespace.
If you're running from a worktree instead of an installed binary, point the command atuv 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.jsonby hand:
{ "mcpServers": { "zsnoop": { "command": "zsnoop-mcp" } } }
- New here?Start with theonboarding 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 viauv 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
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 runspip-auditautomatically wheneverpyproject.tomloruv.lockchange.
Provides shell access to execute commands and interact with the local file system.
Rent a real Linux VPS as an AI agent — pay USDC (x402 on Base) or card, SSH in under 60s, no signup; provision, exec, firewall, and storage.
A comprehensive MCP server for configuring and managing Cisco Intersight.
SSH server management with zero-token SFTP file transfer and SOCKS proxy support
A local server that allows AI to execute Windows CMD commands, read/write files, and manage directories within a specified path.
awaBerry Agentic allows for secure remote access to any terminal based device for workflows allowing any Agent and Large Language Model based routine to execute commands on your devices for getting access to required data - and to also write genrated data back.
A cross-platform filesystem server for Linux, macOS, and Windows with secure path restrictions.
A Node.js MCP server for managing local files, processes, and terminal sessions.
A server providing comprehensive file system operations, automatically downloaded and built on first use.
A server for performing filesystem operations such as reading/writing files, managing directories, and searching.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
