Hiberden

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 that launches local servers over stdio: Claude Desktop / Claude Code, OpenAI's Agents SDK and Codex CLI, Gemini CLI, 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. It makes no network requests of its own.

Versions. The Hiberden app (2.0.0, for Windows, macOS and Linux) ships connector 2.0.0 inside it. The latest release on this repository's releases page, the standalone connector downloads on cdn.hiberden.app and the agaveis/hiberden-mcp Docker image are connector 1.3.2. Where this README describes something the two builds do differently, it names the build.

Read + verify by default

The server advertises and answers the read/verify tools below by default, and nothing mutates configuration. At the default tier the server writes what verify_copy records after it checks the medium (the copy's status, its verify-pass provenance, meaning which algorithm ran and when the last full pass succeeded, and an audit-log row), an audit-log row for each refused call to a tool above the tier, and the catalog's per-file index for an archive written before that index existed, built from its local or NAS copy. Connector 1.3.2 builds that index when find_file or list_archive_files runs; 2.0.0 builds it once, when the server starts. When the server starts it also creates an empty catalog if there is none at the path, and opening a catalog from an older version brings its schema up to date.

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 (Settings, then MCP, Access level). A tool above the active tier is not advertised, and a call to one is refused and recorded in the audit log. Deletes also need a separate delete override, off by default. The levels are described at https://hiberden.app/mcp.

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.

• Disk and NAS. The copy is re-read and re-hashed. When a copy's file is not found, connector 2.0.0 marks it Missing only if its location answers, and otherwise changes nothing; 1.3.2 marks it Missing whenever its file is not found, including when its disk is unplugged or its share is off.
• Tape. It re-reads a tape copy stored as a single .tar file, such as one adopted by the hiberden scan-tape command. Every tape copy the Hiberden desktop writes is stored in parts, which verify_copy cannot read: 2.0.0 refuses those copies and changes nothing, and 1.3.2 can mark them Missing, so do not run 1.3.2's verify_copy on a tape copy the desktop wrote. On tape, 2.0.0 marks a copy Verified only from a cold read, one where it mounted the cartridge itself (cold: true unmounts and remounts first). With a different cartridge in the drive, 2.0.0 changes nothing, and it names the cartridge to load when the catalog records which one holds the copy.
• Cloud (S3). Read-back verify runs in the Hiberden desktop app, not here. For a cloud copy the tool returns a message that the copy was not checked here, so it has neither passed nor failed. That 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, ~/Library/Application Support/Hiberden/catalog.db on macOS (connector 2.0.0, inside the Hiberden app), 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 connector 1.3.2, the same build as the Windows bundle on the releases page. 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). Like the OS keyrings on other platforms, it keeps the key from other users on the machine; 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 path for this computer (see Catalog selection above).

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 co