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 (BETA)

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, archives, verifies and restores with no display server and no network — the whole point of the kit is that an air-gapped or headless machine can run it.

What BETA means here, precisely:

• Licensing is not wired on Linux yet. The kit is unlicensed and unrestricted; entitlement arrives with Linux GA. Nothing you archive now becomes unreadable later: the format and catalog are identical across platforms.
• The desktop app is Windows-only today. Linux is the CLI + connector.
• 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

• 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).