mcp-trove

mcp-trove

An MCP server that manages a trove: a git-backed vault holding two kinds ofentry — plaintext snippets (searchable Markdown, with images and diagrams)and secrets stored encrypted at rest, so the whole vault can be pushed toa private remote without exposing them. A trove holds both treasures (secrets)and finds (snippets).

The server is the deterministic writer over the vault: the calling model composesand cleans content, the server guarantees placement, slug, frontmatter,encryption and index — always the same, no drift.

Install

pip install mcp-trove        # or: uv add mcp-trove

pip install is self-contained — encryption uses the age algorithm through thepyrage binding, so no external binary is required.

Configure

The vault root comes from the TROVE_PATH environment variable. Register theserver with your MCP client (Claude Code shown):

"trove": {
  "type": "stdio",
  "command": "uv",
  "args": ["--directory", "/path/to/mcp-trove", "run", "mcp-trove"],
  "env": { "TROVE_PATH": "/path/to/your/trove" }
}

Then call trove_init once to scaffold the vault and generate the age keypair.The private key is written outside the repo (default ~/.config/trove/key); thepublic recipient is committed in trove.toml.

Back up your private key off-machine (e.g. a password manager). Without itthe encrypted secrets are unrecoverable, even for you. On a new machine youclone the git vault and restore the key separately — cloning alone cannotdecrypt, by design.

Key management

There are two keys, and only one is secret.

• Public recipient (age1...) — committed in trove.toml underrecipients. Secrets are encrypted to it. Safe to share.
• Private key (AGE-SECRET-KEY-1...) — decrypts secrets. Never commit it.

Where it lives. Trove looks for the private key in this order:

1. TROVE_KEY_PATH environment variable, if set.
2. key_path under [trove] in trove.toml, if set.
3. Default: ~/.config/trove/key.

File format. A plain text file containing a single AGE-SECRET-KEY-1...line (lines starting with # are ignored). Keep it chmod 600.

Creating it. trove_init generates the keypair on first run: it writes theprivate key to the resolved path (mode 600) and records the public recipient introve.toml. You don't create it by hand.

Backing it up. Copy that single file somewhere off this machine — yourpassword manager is ideal. This is the only thing that cannot be regenerated.

Restoring on another machine.

mkdir -p ~/.config/trove
# paste your backed-up key into the file, one AGE-SECRET-KEY-1... line:
$EDITOR ~/.config/trove/key
chmod 600 ~/.config/trove/key
git clone <your-private-vault-repo> /path/to/your/trove   # the snippets + encrypted secrets
export TROVE_PATH=/path/to/your/trove

The git clone brings the vault (snippets and encrypted secrets); the key filebrings the ability to decrypt. With both in place, trove_get_secret works.

Reading secrets without the MCP

The MCP is a convenience, not a lock-in. The package ships a trove commandalongside the server, so you can read and browse the vault straight from aterminal — no MCP client running, and no external age binary (decryption goesthrough the bundled pyrage). It reads the same TROVE_PATH and private key theserver uses.

trove get jira                      # decrypt and print all fields
trove get jira --field password     # print one raw value (pipe-friendly)
trove get jira --field password --clip   # copy to clipboard, keep it off-screen
trove get jira --json               # machine-readable dump
trove list                          # list every entry
trove search grafana --kind secret  # search (metadata only for secrets)

--clip shells out to the platform clipboard tool (pbcopy, wl-copy, xclip,xsel, or clip); if none is present it errors instead of printing.

As a low-level fallback, secrets are plain age files (ASCII-armored,-----BEGIN AGE ENCRYPTED FILE-----), so the standard age CLI decrypts themtoo:

age -d -i ~/.config/trove/key <trove>/secrets/<category>/<slug>.age

rage (the Rust implementation) works the same way. Security lives entirely inthe private key, not in the server: whoever holds ~/.config/trove/key can readevery secret, with or without the MCP.

Note on Markdown readers (Obsidian, etc.): the secrets/ folder looks emptybecause those tools list only .md files, and secrets are .age payloads plus.meta.yaml sidecars. The files are there — enable "Detect all file extensions"to see them. The .age stays unreadable (encrypted) and the .meta.yaml showsonly title and tags, never values. Use Markdown readers for snippets/; managesecrets through the MCP tools or the age CLI.

Tools

Layout

<trove>/
  snippets/<domain>/<sub>/<slug>.md     plaintext markdown + frontmatter
  secrets/<category>/<slug>.age          encrypted payload (armored age)
  secrets/<category>/<slug>.meta.yaml    cleartext metadata, never values
  _assets/                               images, diagrams
  INDEX.md                               generated
  trove.toml                             vault config (recipients, language)

Snippets render in any Markdown reader (Obsidian, VS Code, GitHub). The index andsearch read only cleartext metadata for secrets, so they can never leak a value.

Security model

• Encryption is delegated to vetted code (age/pyrage); none is written here.
• The private key lives outside the repo and is git-ignored.
• trove_add_secret encrypts in memory; plaintext never touches disk.
• trove_init installs a pre-commit hook that blocks committing a private key,and enables it automatically (core.hooksPath) when the vault is a git repo.
• trove_doctor flags any cleartext under secrets/ or a key in the tree, andreminds you when a git remote is configured.

Cleartext metadata caveat. Secret values are encrypted, but the.meta.yaml sidecars — titles, tags, category names — are cleartext and getpushed with the vault. Keep the remote private and avoid putting sensitivedetails in secret titles (prefer "Prod DB" over "Prod DB root password h***").

Development

uv sync --extra dev
uv run pytest
uv run ruff check src tests

mcp-trove (Italiano)

Server MCP che gestisce un trove: un vault versionato con git che contiene duetipi di voce — snippet in chiaro (Markdown cercabile, con immagini e schemi) esegreti salvati cifrati a riposo, così l'intero vault si pubblica su unremote privato senza esporli. Un trove custodisce sia i tesori (i segreti) sia iritrovamenti (gli snippet).

Il server è lo scrittore deterministico del vault: il modello compone e ripulisceil contenuto, il server garantisce collocazione, slug, frontmatter, cifratura eindice — sempre uguali, senza deriva.

Installazione

pip install mcp-trove

L'installazione è autosufficiente: la cifratura usa l'algoritmo age tramite ilbinding pyrage, nessun binario esterno richiesto.

Configurazione

La radice del vault arriva dalla variabile d'ambiente TROVE_PATH. Registra ilserver nel tuo client MCP (esempio Claude Code) come mostrato sopra, poi chiamatrove_init una volta per creare il vault e generare la coppia di chiavi age.

Fai un backup della chiave privata fuori dalla macchina (es. passwordmanager). Senza, i segreti cifrati sono irrecuperabili, anche per te. Su un PCnuovo cloni il vault git e ripristini la chiave a parte: clonare e basta nondecifra, per scelta.

Gestione della chiave

Le chiavi sono due, e solo una è segreta.

• Recipient pubblico (age1...) — committato in trove.toml sottorecipients. I segreti vengono cifrati verso di lui. Si può condividere.
• Chiave privata (AGE-SECRET-KEY-1...) — decifra i segreti. Mai committarla.

Dove vive. Trove cerca la chiave privata in quest'ordine:

1. variabile d'ambiente TROVE_KEY_PATH, se impostata;
2. key_path sotto [trove] in trove.toml, se impostato;
3. default: ~/.config/trove/key.

Formato del file. Un file di testo con una sola riga AGE-SECRET-KEY-1...(le righe che iniziano con # sono ignorate). Tienilo a chmod 600.

Creazione. trove_init genera la coppia al primo avvio: scrive la chiaveprivata nel path risolto (permessi 600) e registra il recipient pubblico introve.toml. Non la crei a mano.

Backup. Copia quel singolo file fuori da questa macchina — il passwordmanager è il posto ideale. È l'unica cosa che non si può rigenerare.

Ripristino su un'altra macchina.

mkdir -p ~/.config/trove
# incolla la chiave salvata nel file, una riga AGE-SECRET-KEY-1...:
$EDITOR ~/.config/trove/key
chmod 600 ~/.config/trove/key
git clone <repo-privato-del-vault> /path/to/your/trove   # snippet + segreti cifrati
export TROVE_PATH=/path/to/your/trove

Il clone git porta il vault (snippet e segreti cifrati); il file chiave porta lacapacità di decifrare. Con entrambi a posto, trove_get_secret funziona.

Leggere i segreti senza l'MCP

L'MCP è una comodità, non un vincolo. Il package installa un comando troveaccanto al server, così leggi e navighi il vault direttamente da terminale —senza client MCP attivo e senza binario age esterno (la decifratura passa perpyrage già incluso). Usa lo stesso TROVE_PATH e la stessa chiave privata delserver.

trove get jira                      # decifra e stampa tutti i campi
trove get jira --field password     # stampa un solo valore grezzo (per pipe)
trove get jira --field password --clip   # copia negli appunti, fuori dallo schermo
trove get jira --json               # output leggibile dalle macchine
trove list                          # elenca ogni voce
trove search grafana --kind secret  # cerca (solo metadata per i segreti)

--clip invoca il tool clipboard di sistema (pbcopy, wl-copy, xclip,xsel o clip); se non ce n'è nessuno dà errore invece di stampare.

Come fallback di basso livello, i segreti sono normali file age (in armorASCII, -----BEGIN AGE ENCRYPTED FILE-----), quindi anche la CLI standard ageli decifra:

age -d -i ~/.config/trove/key <trove>/secrets/<categoria>/<slug>.age

Anche rage (l'implementazione Rust) funziona allo stesso modo. La sicurezza statutta nella chiave privata, non nel server: chi possiede ~/.config/trove/keylegge ogni segreto, con o senza l'MCP.

Nota sui lettori Markdown (Obsidian, ecc.): la cartella secrets/ apparevuota perché quegli strumenti elencano solo i file .md, mentre i segretisono payload .age più sidecar .meta.yaml. I file ci sono — attiva "Detect allfile extensions" per vederli. Il .age resta illeggibile (cifrato) e il.meta.yaml mostra solo titolo e tag, mai i valori. Usa i lettori Markdown pergli snippets/; i segreti gestiscili con gli strumenti MCP o con la CLI age.

Modello di sicurezza

• La cifratura è delegata a codice collaudato (age/pyrage), nessuna scrittaqui.
• La chiave privata vive fuori dal repo ed è esclusa da git.
• trove_add_secret cifra in memoria; il testo in chiaro non tocca mai il disco.
• trove_init installa un hook pre-commit che blocca il commit di una chiaveprivata e lo abilita da solo (core.hooksPath) quando il vault è un repo git.
• trove_doctor segnala qualsiasi file in chiaro sotto secrets/ o una chiavenell'albero, e ti avvisa quando è configurato un remote git.

Caveat metadati in chiaro. I valori dei segreti sono cifrati, ma i sidecar.meta.yaml — titoli, tag, nomi di categoria — sono in chiaro e vengono pushaticol vault. Tieni il remote privato ed evita dettagli sensibili nei titoli(meglio "Prod DB" che "Prod DB password di root h***").