MCP Rule34

mcp-rule34

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 mcp add rule34 --env RULE34_USER_ID=your-id --env RULE34_API_KEY=your-key -- npx -y mcp-rule34

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

{

"mcpServers": { "rule34": { "command": "npx", "args": ["-y", "mcp-rule34"], "env": { "RULE34_USER_ID": "your-id", "RULE34_API_KEY": "your-key" } } } }

Node 24 or later is required. The two credentials are required; everything else under Configuration is optional.

With Docker

{

"mcpServers": { "rule34": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "RULE34_USER_ID", "-e", "RULE34_API_KEY", "ghcr.io/smeet666/mcp-rule34: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 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.

import { Rule34Client } from "mcp-rule34/client";

const client = new Rule34Client({ credentials: { userId: "…", apiKey: "…" } }); const { data, cached } = await client.searchPosts({ tags: ["example"], limit: 5 }); console.log(data.total, 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.

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