agaveis/hiberden-mcp repository overview

⁠hiberden-mcp: Hiberden MCP server

Exposes the Hiberden archive engine (hiberden-core) as Model Context Protocol⁠ tools over the stdio transport (newline-delimited JSON-RPC 2.0).

MCP is an open, vendor-neutral standard, so this one server is drivable from any MCP client: Claude Desktop / Claude Code, OpenAI's Agents SDK and ChatGPT desktop, Gemini, Cursor, Windsurf, and others. There is no model and no API key in this process. The client brings the LLM; this binary only answers tool calls against the local catalog. In its default mode it performs no network I/O.

⁠Read + verify by default

The server advertises and answers the read/verify tools below by default, and nothing mutates configuration. The only state any default tool ever writes is what verify_copy records: the copy's status, its verify-pass provenance (which algorithm ran, when the last full pass succeeded), and an audit-log row for each completed verify — and it only does that after a genuine read-back from the medium.

Write and delete tools (catalog management, destinations, policies) ARE implemented, but behind a catalog-persisted permission tier that defaults to read-only and is only changeable in the Hiberden desktop app's settings; a tool above the active tier is neither advertised nor accepted. See docs/Hiberden_MCP_Command_Surface_and_Permission_Model.md (which supersedes docs/mcp/write-gate-design.md).

⁠Read + verify tools (always on)

verify_copy is the differentiator: it is proof from the actual medium, not a stored flag. Identify the copy by archive_id + destination_id. It works for disk and NAS copies and for tape copies (the cartridge is mounted and read back). Cloud (S3) read-back verify runs in the Hiberden desktop app, not here: for a cloud copy the tool returns a clear message that the copy was checked in the desktop, not here, so it has not passed or failed. That message is a not-attempted result, not a verification failure.

Adding archives (writing bytes), save, and restore are not exposed here. Catalog, destination, and policy configuration tools exist behind the permission tier described above; at the default read-only tier they are neither advertised nor accepted.

⁠Catalog selection

The server reads the single catalog shared by the desktop app, the CLI, and this server. Path resolution:

1. The HIBERDEN_DB environment variable, if set.
2. Otherwise %LOCALAPPDATA%\Hiberden\catalog.db on Windows, or ~/.hiberden/catalog.db on Linux.

The catalog is opened fresh per tool call (sub-millisecond) rather than held for the process lifetime. With WAL mode and a busy timeout, the desktop app and this server can run against the same catalog.db at the same time without a multi-process locking hazard.

All diagnostics go to stderr. stdout carries the JSON-RPC channel; anything written to stdout that is not a JSON-RPC message corrupts the stream.

⁠Linux headless kit

Linux binaries are published on the releases⁠ page and at cdn.hiberden.app. They are built on Ubuntu 22.04, so they run on Ubuntu 22.04+, Debian 12+, and equivalents; verified on debian:bookworm-slim and ubuntu:22.04.

curl -fsSLO https://cdn.hiberden.app/downloads/hiberden-cli-linux-x86_64
curl -fsSLO https://cdn.hiberden.app/downloads/hiberden-cli-linux-x86_64.sha256
sha256sum -c hiberden-cli-linux-x86_64.sha256      # verify before running it
chmod +x hiberden-cli-linux-x86_64
./hiberden-cli-linux-x86_64 --version

hiberden-mcp-linux-x86_64 is the same connector as the Windows build. The CLI (hiberden) catalogs and archives with no display server and no network — the whole point of the kit is that an air-gapped or headless machine can run it.

Linux reached general availability on 2026-08-11 at version 1.3.1, alongside Windows. What that does and does not cover, precisely:

• Writing a new archive needs a license. Reading your data back never does, license or not. Kits published before GA are ungated and stay that way; entitlement applies from the first post-GA kit onward. Nothing you archive now becomes unreadable later: the format and catalog are identical across platforms.
• The desktop app runs on Linux too, as a signed .deb and .AppImage from hiberden.app/linux⁠. The macOS build for Apple Silicon is at hiberden.app/download⁠.
• Tape on Linux is unproven on hardware. The backend targets the open-source LTFS implementation and has never run against a drive on any platform. Use HIBERDEN_TAPE_FAKE=1 to exercise the flows without one.
• Archives are signed by a per-install Ed25519 identity stored under ~/.hiberden/keys/ (owner-only). It is the same custody model as the OS keyrings on other platforms, and no stronger: it is not hardware-backed.

⁠Setup

The binary self-installs into known MCP clients:

hiberden-mcp install          # auto-detect Claude Desktop / Cursor / Windsurf and write their config
hiberden-mcp install --print  # print a paste-ready snippet instead of touching anything
hiberden-mcp uninstall        # remove the hiberden entry from detected clients
hiberden-mcp help             # show usage

install writes (or updates) an mcpServers.hiberden entry pointing at this executable. It is zero-config for the catalog: the entry only pins HIBERDEN_DB when you already have it set in your environment, otherwise it relies on the default %LOCALAPPDATA%\Hiberden\catalog.db path.

⁠Manual configuration

To wire it up by hand, add this to your client's config (Claude Desktop: claude_desktop_config.json; Claude Code: .mcp.json; Cursor / Windsurf use the same mcpServers shape). command is the path to the executable. env is optional: include HIBERDEN_DB only if your catalog lives somewhere other than the default path.

{
  "mcpServers": {
    "hiberden": {
      "command": "C:/path/to/hiberden-mcp.exe",
      "env": { "HIBERDEN_DB": "C:/path/to/catalog.db" }
    }
  }
}

⁠Smoke test (no client needed)

This pipes three requests (initialize, list tools, read coverage) straight into the binary:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"coverage_status","arguments":{}}}' \
  | HIBERDEN_DB=path/to/catalog.db hiberden-mcp

⁠Container image

The image on Docker Hub, agaveis/hiberden-mcp, is the same connector binary in a debian:bookworm-slim container. It carries no catalog: it starts, reports itself, and advertises the read-only tool surface, but there are no archives to answer questions about. This is not how you run Hiberden. For real use, install Hiberden from https://hiberden.app⁠.

The image exists so MCP directories can run their introspection handshake (initialize, then tools/list) against the connector in a Linux sandbox, and so anyone can inspect the advertised tool surface without installing anything.

To point it at a real catalog, mount one and set HIBERDEN_DB:

docker run --rm -i -v /var/lib/hiberden:/cat -e HIBERDEN_DB=/cat/catalog.db agaveis/hiberden-mcp

The connector opens it read-only apart from verify's status writes, and never reads the OS keyring.

⁠Security

• Local-only and closed-domain. The server is read + verify only and performs zero network I/O; the only state it writes is the copy status verify_copy stamps after a read-back. It never sends data to Hiberden or any third party.
• No API key and no LLM are stored in the binary, so there is nothing to steal there.
• verify_copy gives ground-truth physical state: it re-reads and re-hashes the actual medium, so even a manipulated assistant cannot fabricate a "Verified".
• Tool annotations (readOnlyHint, destructiveHint, and so on) are hints, not guarantees. Prompt injection is an unsolved industry-wide problem. The architecture here is conservative by design; that is not a claim of immunity.

⁠Privacy

The server runs entirely on your own machine, holds no account or API key, and in its default read-and-verify mode performs zero network I/O — it never sends your catalog or your files to Hiberden or any third party. The only state any default tool writes is the copy status verify_copy stamps after a genuine read-back. Full details (what the server reads, what it never does, the role of the separate AI client, and credential handling) are in PRIVACY.md⁠, hosted at https://hiberden.app/mcp/privacy⁠.

⁠Tape caveat

Tape support is in beta and has not been validated on physical tape hardware in this implementation. The design never speaks SCSI directly and treats tape as a filesystem via LTFS tooling, so any tape the LTFS tooling can mount should work by construction. That is an architectural property, not a tested hardware matrix. Do not read these notes as a guarantee for any specific drive or generation.

For testing without a drive, the tape backend can run against a fake backend: set HIBERDEN_TAPE_FAKE=1 (and optionally HIBERDEN_TAPE_FAKE_ROOT=<dir> to point at a directory standing in for the mounted volume).

Website: https://hiberden.app⁠

Listing and source: https://github.com/Agaveis/hiberden-mcp⁠

Built and maintained by AgaveIS⁠, Scottsdale, Arizona.