Stashbox MCP Server

mcp-stashbox

A stash-box is a shared metadata catalogue: it records scenes, the performers credited on them, the studios that released them, and the tags they are filed under, each curated by submission and review. A catalogue holds no media — a record names where something was published and carries nothing of it — and it identifies a file by the fingerprints computed from it. Five such catalogues run independently, each issuing its own key to a registered account.

This server connects a chat client to all of them at once. You can search the scenes, performers, studios and tags of every catalogue you hold a key for, read one record as a single card assembled from every catalogue that holds it, identify a file from its fingerprints, and ask what each catalogue was measured answering. It needs a key per catalogue, and reads only the catalogues it has one for.

Version française

---

Install

One-click install

Claude Code

claude mcp add stashbox --env STASHBOX_STASHDB_KEY=your-key -- npx -y mcp-stashbox

Claude Desktop, Cursor, and any client using the standard config format

{
  "mcpServers": {
    "stashbox": {
      "command": "npx",
      "args": ["-y", "mcp-stashbox"],
      "env": {
        "STASHBOX_STASHDB_KEY": "your-key"
      }
    }
  }
}

Node 24 or later is required. Set a key for each catalogue you want read; the others are named as absent from every answer.

With Docker

{
  "mcpServers": {
    "stashbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "STASHBOX_STASHDB_KEY",
        "ghcr.io/smeet666/mcp-stashbox:2.1.0"
      ]
    }
  }
}

-i keeps stdin open, which is where the protocol travels, and -t is left out because a TTY rewrites the stream. The container needs outbound HTTPS to the catalogues you hold keys for, and the keys from your environment: no volume, no port.

Bundle, without npm

Download mcp-stashbox-2.1.0.mcpb from the latest release and open it. A client that supports MCP bundles installs it on its own, with no npm to run. The keys are still set in the client's configuration.

What you can ask

• "Which catalogues am I actually reading?"
• "Find the performers credited under that name."
• "Read me that studio's record."
• "What is this file? Here is its MD5."
• "Which scenes did those two perform in together?"

The ordinary path runs from a search to a card: a row carries an id written instance:uuid, and the record tool reads it on every catalogue that holds it.

The catalogues

They answer different surfaces: StashDB answers every route this server knows, and the others answer fewer. get_sources states what each was measured answering and the day it was measured. A catalogue with no key is named as absent from every answer, so an answer holding rows from some of them is never read as the whole.

Tools

Every search takes two exclusive paths. query runs each catalogue's own text index, which reads the words as a union. The typed arguments narrow as an intersection. Writing both is refused.

get_sources

States what each configured catalogue was measured answering, and the day its surface was read. It reaches no catalogue and takes no argument.

In return: one entry per catalogue with its name, its identifier prefix, whether a key is held for it in this install, the variable to set when none is, and the routes it answers. Whether a key is held is a fact about this install and changes nothing about what the catalogue does.

search_scenes

Searches the scenes.

In return: rows carrying the id written instance:uuid, which get_scene takes, and what names the record. A row leaves the synopsis, the link lists and the editing stamps to the card, since none of those separates two releases. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, or an emptiness it established. Counts are never added across catalogues. A search written with words alone reads the first rows each text index answers with, since those routes take no page.

search_performers

Searches the performers.

alias is declared and never sent. No catalogue's faceted route applies it: a request carrying it answers as wide as one carrying none, so it is left out and the answer names it as a narrowing nobody received.

In return: the rows and the per-catalogue accounting search_scenes returns.

search_studios

Searches the studios.

In return: the rows and the per-catalogue accounting search_scenes returns.

search_tags

Searches the tags.

In return: the rows and the per-catalogue accounting search_scenes returns.

get_scene

Reads one scene as a single card.

In return: one card, read on every catalogue that holds the record and reached by the link each of them publishes to the same record elsewhere. Every value names the catalogues that said it, and where they disagree the reading nobody preferred is published beside the one that won. Left out, the registry's own order stands, and every card states the order applied.

get_performer

Reads one performer as a single card.

studios is the whole table of studios they are credited on, which runs to hundreds of rows.

In return: the card get_scene returns, for a performer.

get_studio

Reads one studio as a single card.

In return: the card get_scene returns, for a studio.

get_tag

Reads one tag as a single card.

In return: the card get_scene returns, for a tag.

find_by_fingerprint

Identifies a file from the hashes held for it.

MD5 and OSHASH name the bytes of a file. PHASH states a likeness, which a re-encode, a crop or another scene from the same shoot can satisfy: read a PHASH match as a resemblance rather than as an identity.

In return: each record reached, answered as one card read on every catalogue that holds it.

What an answer states about the catalogues

Every answer accounts for each catalogue separately, because merging them would lose what a caller needs. A catalogue that failed, one nobody asked, and one that answered with nothing are three different things, and they are reported as three. Counts stay beside the catalogue that produced them and are never added up. On a card, each value names the catalogues that said it, and a disagreement is published rather than resolved silently.

Configuration

A key per catalogue, and everything else optional. All of it goes in the env block of your client config.

Each catalogue issues its key to a registered account, in that account's settings. This server ships no key of its own, and each user brings their own. A value outside its range falls back to the default, and the reason is written to stderr.

Errors

Every failure carries one of six codes, a message, and where it helps a hint naming the next move.

A catalogue that failed is reported per catalogue rather than failing the whole answer, so one silent catalogue never hides the others.

As a library

The layer reading the catalogues is published on its own, with its pacing, its cache and its errors, and with no protocol attached.

import { Catalogues } from "mcp-stashbox/client";

const client = new Catalogues();
const read = await client.searchPerformers({ name: "example", limit: 5 });
console.log(read.data.rows.length, read.cached);

Each read answers { data, cached }, and throws an error carrying one of the six codes. The one-second floor between two requests holds here as well.

Pacing and attribution

Requests go out one at a time with at least a second between them, and that floor holds however the server is configured. The User-Agent always ends with the project identity and an address where a person can be reached.

Every record carries the address of its page on the catalogue it came from, and a card carries the link each catalogue publishes to the same record elsewhere. The catalogues are built by the people who submit and review their records.

This MCP server is an unofficial project, with no affiliation to any of the catalogues it reads.

Privacy

This server collects nothing about you and sends nothing to its author. It runs on your machine, contacts only the catalogues you hold a key for, holds its answers in memory while it runs, and writes nothing to disk. Your keys are read from the environment and sent to their own catalogue alone. PRIVACY.md states what a request carries and which settings change any of it.

Development

npm install
npm run build:fixtures
npm test
npm run check

Tests run against generated fixtures and make no network request. The live suite, npm run test:live, makes one request per route and runs nightly against the catalogues themselves.

Contributing

Bugs, questions and ideas belong in the issue tracker. Pull requests are welcome; opening an issue first helps agree on the shape of the change. See CONTRIBUTING.md.

License

MIT, see LICENSE. The records belong to the catalogues and to the people who built them.

---

mcp-stashbox (français)

English version

Un stash-box est un catalogue de métadonnées partagé : il enregistre des scènes, les interprètes qui y sont crédités, les studios qui les ont publiées, et les étiquettes sous lesquelles elles sont rangées, le tout tenu par soumission et relecture. Un catalogue ne contient aucun média — une fiche nomme où quelque chose a été publié et n'en emporte rien — et il identifie un fichier par les empreintes calculées dessus. Cinq catalogues de ce type fonctionnent indépendamment, chacun délivrant sa propre clé à un compte enregistré.

Ce serveur relie un client de conversation à tous à la fois. On peut chercher les scènes, les interprètes, les studios et les étiquettes de chaque catalogue dont on détient une clé, lire une fiche sous forme d'une carte unique assemblée depuis tous les catalogues qui la détiennent, identifier un fichier par ses empreintes, et demander ce que chaque catalogue a été mesuré répondant. Il demande une clé par catalogue, et ne lit que ceux dont il en a une.

Installation

Installation en un clic

Claude Code

claude mcp add stashbox --env STASHBOX_STASHDB_KEY=votre-cle -- npx -y mcp-stashbox

Claude Desktop, Cursor, et tout client au format de configuration standard

{
  "mcpServers": {
    "stashbox": {
      "command": "npx",
      "args": ["-y", "mcp-stashbox"],
      "env": {
        "STASHBOX_STASHDB_KEY": "votre-cle"
      }
    }
  }
}

Node 24 ou plus récent est nécessaire. Posez une clé par catalogue à lire ; les autres sont nommés comme absents de chaque réponse.

Avec Docker

{
  "mcpServers": {
    "stashbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "STASHBOX_STASHDB_KEY",
        "ghcr.io/smeet666/mcp-stashbox:2.1.0"
      ]
    }
  }
}

-i garde l'entrée standard ouverte, qui est le canal du protocole, et -t est omis parce qu'un TTY réécrit le flux. Le conteneur a besoin d'un accès HTTPS sortant vers les catalogues dont vous détenez les clés, et de ces clés prises dans votre environnement : aucun volume, aucun port.

Bundle, sans npm

Téléchargez mcp-stashbox-2.1.0.mcpb depuis la dernière publication et ouvrez-le. Un client qui gère les bundles MCP l'installe seul, sans npm à lancer. Les clés se posent toujours dans la configuration du client.

Ce qu'on peut demander

• « Quels catalogues est-ce que je lis réellement ? »
• « Trouve les interprètes crédités sous ce nom. »
• « Lis-moi la fiche de ce studio. »
• « Qu'est-ce que ce fichier ? Voici son MD5. »
• « Dans quelles scènes ces deux-là ont-ils joué ensemble ? »

Le chemin ordinaire va d'une recherche à une carte : une ligne porte un id écrit instance:uuid, et l'outil de fiche le lit sur chaque catalogue qui le détient.

Les catalogues

Ils répondent des surfaces différentes : StashDB répond à toutes les routes que ce serveur connaît, les autres à moins. get_sources dit ce que chacun a été mesuré répondant et le jour de la mesure. Un catalogue sans clé est nommé comme absent de chaque réponse, si bien qu'une réponse portant les lignes de certains ne se lit jamais comme l'ensemble.

Les outils

Chaque recherche prend deux chemins exclusifs. query interroge l'index textuel de chaque catalogue, qui lit les mots comme une union. Les arguments typés resserrent comme une intersection. Écrire les deux est refusé.

get_sources

Dit ce que chaque catalogue configuré a été mesuré répondant, et le jour où sa surface a été lue. Il ne joint aucun catalogue et ne prend aucun argument.

En retour : une entrée par catalogue avec son nom, son préfixe d'identifiant, la présence d'une clé dans cette installation, la variable à poser quand il n'y en a pas, et les routes auxquelles il répond. La présence d'une clé est un fait sur cette installation et ne change rien à ce que le catalogue fait.

search_scenes

Cherche les scènes.

En retour : des lignes portant l'id écrit instance:uuid, que get_scene reprend, et ce qui nomme la fiche. Une ligne laisse à la carte le synopsis, les listes de liens et les horodatages d'édition, dont aucun ne distingue deux publications. La réponse dit par catalogue laquelle des trois il a rencontrées : un échec, un catalogue que personne n'a interrogé, ou un vide qu'il a établi. Les comptes ne sont jamais additionnés entre catalogues. Une recherche écrite avec des mots seuls lit les premières lignes que rend chaque index textuel, ces routes ne prenant aucune page.

search_performers

Cherche les interprètes.

Documentation truncated — see the full README on GitHub.