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. A macOS beta 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

Security