mcp-rule34
[npm]
[CI]
[license]
[LobeHub]
rule34.xxx is a large image board whose posts are indexed
entirely by tags, and it publishes an API for reading them. A post carries its
identifier, the address of its page and of its file, its dimensions, the score
its viewers gave it, its rating, and the full list of tags it was filed under.
The site holds tens of millions of posts and answers a tag search with the number
it matched.
This server connects a chat client to that index. You can search the posts by
tags, combining required tags, alternatives and exclusions, read one post's
record by its identifier, and look up how the site spells a tag before searching
on it. It needs an account and an API key, which the site issues per person.
Version française
Install
Claude Code
Claude Desktop, Cursor, and any client using the standard config format
Node 24 or later is required. The two credentials are required; everything else
under Configuration is optional.
With Docker
-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
api.rule34.xxx and rule34.xxx, and the two credentials from your environment:
no volume, no port.
Bundle, without npm
Download mcp-rule34-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 credentials are still set in the client's configuration.
What you can ask
- "How does the site spell that tag?"
- "Find posts tagged with those two, sorted by score."
- "Same search, leaving out monochrome."
- "Read me the record for post 1234567."
- "How many posts does that search match?"
The ordinary path runs from a tag lookup to a search: find_tags gives the
spelling the site uses, and search_posts takes it.
Tools
Look a tag up before searching on it. The site indexes by tag alone, and a
tag it does not hold matches nothing, which reads as an empty result rather than
as a misspelling.
find_tags
Finds how the site spells a tag.
In return: query as it was sent, and tags, each with the spelling the site
uses and the number of posts carrying it.
search_posts
Searches the posts by tags.
media_type is read off the site's own tags, so the classification is as good as
the tagging. The two ratings above are the only ones the site holds: any other
value answers zero posts and no error, which would hand back an absence the site
never had.
In return: tags, any_of and exclude as the site spells them; query,
the search as it was sent in the site's own language; total, the posts the
whole search matches as counted by the site; and the posts themselves, each with
its id, post_url, file_url, preview_url, sample_url, width,
height, score, rating and tags. The score is the site's own and it is
updated once a day.
get_post
Reads one post's record.
In return: the post a search row carries, with its full tag list.
Configuration
The two credentials are required. Everything else is optional, and all of it goes
in the env block of your client config.
Where the credentials come from. Sign in, open
Account options, and find
the row named API Access Credentials. It shows &api_key=…&user_id=…, and
those two values are what goes in the configuration above. If the key is empty,
tick Generate New Key? and save.
The site issues one key per person, and asks that applications serving its
content display no advertising and put it behind no paywall. This server ships no
key of its own, and each user brings their own. Started without credentials, it
runs, publishes its tools, and answers every call by naming the two variables to
set: it sends no request it knows the site will refuse.
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.
As a library
The layer reading the site is published on its own, with its pacing, its cache
and its errors, and with no protocol attached.
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.
Reads go to the API the site documents, and the credentials it issues are what
its terms ask automated reading to use. Every result carries the address of the
post's page. Nothing is downloaded: a file address travels through an answer as a
string.
This MCP server is an unofficial project, with no affiliation to rule34.xxx.
Privacy
This server collects nothing about you and sends nothing to its author. It runs
on your machine, contacts api.rule34.xxx and rule34.xxx and nothing else,
holds its answers in memory while it runs, and writes nothing to disk. Your
credentials are read from the environment and sent to that site alone.
PRIVACY.md states what a request carries and which settings change
any of it.
Development
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
site itself.
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 posts and the tags belong to rule34.xxx and to
the people who uploaded them.
mcp-rule34 (français)
English version
rule34.xxx est un grand imageboard dont les publications
sont indexées entièrement par étiquettes, et il publie une API pour les lire. Une
publication porte son identifiant, l'adresse de sa page et de son fichier, ses
dimensions, la note que ses visiteurs lui ont donnée, son classement, et la liste
complète des étiquettes sous lesquelles elle est rangée. Le site contient des
dizaines de millions de publications et répond à une recherche par étiquettes en
donnant le nombre qu'elle a trouvé.
Ce serveur relie un client de conversation à cet index. On peut chercher les
publications par étiquettes, en combinant les étiquettes exigées, les
alternatives et les exclusions, lire la fiche d'une publication par son
identifiant, et vérifier comment le site orthographie une étiquette avant de
chercher dessus. Il demande un compte et une clé d'API, que le site délivre
par personne.
Installation
Claude Code
Claude Desktop, Cursor, et tout client au format de configuration standard
Node 24 ou plus récent est nécessaire. Les deux identifiants sont obligatoires ;
tout le reste, sous Configuration, est facultatif.
Avec Docker
-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 api.rule34.xxx et rule34.xxx, et des deux identifiants pris dans
votre environnement : aucun volume, aucun port.
Bundle, sans npm
Téléchargez mcp-rule34-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 identifiants se posent toujours dans la configuration du client.
Ce qu'on peut demander
- « Comment le site orthographie-t-il cette étiquette ? »
- « Trouve les publications portant ces deux étiquettes, triées par note. »
- « La même recherche, sans monochrome. »
- « Lis-moi la fiche de la publication 1234567. »
- « Combien de publications cette recherche trouve-t-elle ? »
Le chemin ordinaire va d'une recherche d'étiquette à une recherche de
publications : find_tags donne l'orthographe qu'emploie le site, et
search_posts la reprend.
Les outils
Vérifiez une étiquette avant de chercher dessus. Le site indexe par étiquette
seule, et une étiquette qu'il ne connaît pas ne correspond à rien, ce qui se lit
comme un résultat vide plutôt que comme une faute d'orthographe.
find_tags
Trouve l'orthographe d'une étiquette.
En retour : query tel qu'envoyé, et tags, chacune avec l'orthographe
qu'emploie le site et le nombre de publications qui la portent.
search_posts
Cherche les publications par étiquettes.
media_type se lit sur les étiquettes du site lui-même, donc la classification
vaut ce que vaut l'étiquetage. Les deux classements ci-dessus sont les seuls que
le site connaisse : toute autre valeur rend zéro publication et aucune erreur, ce
qui livrerait une absence que le site n'a jamais eue.
En retour : tags, any_of et exclude tels que le site les
orthographie ; query, la recherche telle qu'elle a été envoyée dans la langue
du site ; total, les publications que toute la recherche trouve, tel que le
site les compte ; et les publications elles-mêmes, chacune avec son id,
post_url, file_url, preview_url, sample_url, width, height, score,
rating et tags. La note est celle du site et elle est mise à jour une fois
par jour.
get_post
Lit la fiche d'une publication.
En retour : la publication que porte une ligne de recherche, avec sa liste
complète d'étiquettes.
Configuration
Les deux identifiants sont obligatoires. Tout le reste est facultatif, et tout se
pose dans le bloc env de la configuration du client.
D'où viennent les identifiants. Connectez-vous, ouvrez
Account options, et
trouvez la ligne API Access Credentials. Elle affiche &api_key=…&user_id=…,
et ces deux valeurs sont ce qui va dans la configuration ci-dessus. Si la clé est
vide, cochez Generate New Key? et enregistrez.
Le site délivre une clé par personne, et demande que les applications servant son
contenu n'affichent aucune publicité et ne le placent derrière aucun péage. Ce
serveur n'embarque aucune clé, et chacun apporte la sienne. Démarré sans
identifiants, il tourne, publie ses outils, et répond à chaque appel en nommant
les deux variables à poser : il n'envoie aucune requête dont il sait que le site
la refusera.
Une valeur hors de sa plage retombe sur le défaut, et la raison est écrite sur la
sortie d'erreur.
Erreurs
Chaque échec porte un des six codes, un message, et quand cela aide une
indication du geste suivant.
Comme bibliothèque
La couche qui lit le site est publiée seule, avec son rythme, son cache et ses
erreurs, sans protocole attaché.
Chaque lecture répond { data, cached }, et lève une erreur portant un des six
codes. Le plancher d'une seconde entre deux requêtes tient également ici.
Rythme et attribution
Les requêtes partent une à une avec au moins une seconde entre elles, et ce
plancher tient quelle que soit la configuration. Le User-Agent se termine
toujours par l'identité du projet et une adresse où joindre une personne.
Les lectures passent par l'API que le site documente, et les identifiants qu'il
délivre sont ce que ses conditions demandent d'employer pour une lecture
automatisée. Chaque résultat porte l'adresse de la page de la publication. Rien
n'est téléchargé : une adresse de fichier traverse une réponse comme une chaîne
de caractères.
Ce MCP est un projet non officiel, sans affiliation à rule34.xxx.
Confidentialité
Ce serveur ne collecte rien sur vous et n'envoie rien à son auteur. Il tourne sur
votre machine, ne joint que api.rule34.xxx et rule34.xxx, garde ses réponses
en mémoire le temps qu'il tourne, et n'écrit rien sur le disque. Vos identifiants
sont lus dans l'environnement et envoyés à ce seul site. PRIVACY.md
dit ce qu'une requête emporte et quels réglages changent cela.
Développement
Les tests s'exécutent sur des fixtures engendrées et n'émettent aucune requête.
La suite en direct, npm run test:live, émet une requête par route et tourne
chaque nuit contre le site lui-même.
Contribuer
Les anomalies, les questions et les idées ont leur place dans
le suivi d'incidents. Les
propositions de modification sont bienvenues ; ouvrir un ticket d'abord aide à
s'accorder sur la forme du changement. Voir CONTRIBUTING.md.
Licence
MIT, voir LICENSE. Les publications et les étiquettes appartiennent à
rule34.xxx et aux personnes qui les ont déposées.
