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.0.2"
      ]
    }
  }
}

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