hiberden-mcp: Hiberden MCP server

Exposes the Hiberden archive engine (`hiberden-core`) as [Model Context

Protocol](https://modelcontextprotocol.io) 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

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

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=` to

point at a directory standing in for the mounted volume).