mcp-rule34

mcp-rule34

rule34.xxx 是一个大型图片站，帖子完全通过标签建立索引，并提供读取帖子的 API。每篇帖子都包含其标识符、页面和文件地址、尺寸、浏览者给出的评分、分级，以及它所属的完整标签列表。该网站拥有数千万篇帖子，搜索标签时会返回匹配数量。

此服务将聊天客户端连接到该索引。你可以组合必选标签、备选标签和排除标签来搜索帖子；按标识符读取单篇帖子的记录；还可以在搜索前查询网站对某个标签的拼写。需要账号和 API 密钥，网站会为每位用户单独发放。

法语版本

---

安装

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，以及使用标准配置格式的任何客户端

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

需要 Node 24 或更高版本。两项凭据为必填；配置中的其他所有项目均为可选。

使用 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 会保持标准输入处于打开状态，协议通过这里传输；不使用 -t，因为 TTY 会改写数据流。容器需要通过 HTTPS 访问 api.rule34.xxx 和 rule34.xxx，并需要从环境变量中获取两项凭据：无需挂载卷，也无需开放端口。

打包版，无需 npm

从最新版本下载 mcp-rule34-2.0.2.mcpb 并打开。支持 MCP bundle 的客户端会自动安装，无需运行 npm。仍需在客户端配置中设置凭据。

你可以这样提问

• “这个标签在网站上是怎么拼写的？”
• “查找带有这两个标签、按评分排序的帖子。”
• “进行相同的搜索，但排除 monochrome。”
• “读取帖子 1234567 的记录。”
• “这次搜索匹配了多少篇帖子？”

常见流程是先查询标签，再进行搜索：find_tags 会返回网站使用的拼写，search_posts 则接受该拼写。

工具

工具	功能
find_tags	查找网站对标签的拼写，以及带有该标签的帖子数量。
search_posts	按标签搜索帖子，支持备选标签和排除标签。
get_post	按标识符或地址读取单篇帖子的记录。

搜索前请先查询标签。 网站仅按标签建立索引；如果它没有收录某个标签，就不会匹配到任何内容，结果会显示为空，而不是提示拼写错误。

find_tags

查找网站对标签的拼写。

参数	类型	必填	功能
query	字符串，最多 60 个字符	是	要查询的文本。

返回内容： 原样返回传入的 query，以及 tags；每个标签都包含网站使用的拼写和带有该标签的帖子数量。

search_posts

按标签搜索帖子。

参数	类型	必填	说明
tags	1 到 10 个标签名称组成的数组	是	帖子必须包含的标签。
any_of	1 到 10 个标签名称组成的数组	否	帖子至少必须包含其中一个标签。
exclude	1 到 10 个标签名称组成的数组	否	帖子不得包含其中任何一个标签。
media_type	image、animated、video 或 any，默认值为 any	否	静态图、GIF 或 MP4。
rating	questionable 或 explicit	否	留空时会搜索两者。
sort	score、id、updated 或 random，默认值为 score	否	网站使用的排序方式。
limit	整数，1 到 100，默认值为 20	否	返回的帖子数量。
page	整数，1 到 200，默认值为 1	否	帖子所在的页码。

media_type 根据网站自身的标签读取，因此分类是否准确取决于标签。上述两种评级是网站仅有的评级：任何其他值都会返回零个帖子且不报错，这会返回一个网站上从未存在过的空结果。

返回内容： 网站原样拼写的 tags、any_of 和 exclude；query，即以网站自身语言发送的搜索内容；total，即网站统计的整个搜索匹配帖子数；以及帖子本身，每个帖子包含其 id、post_url、file_url、preview_url、sample_url、width、height、score、rating 和 tags。分数由网站自行计算，每天更新一次。

get_post

读取单个帖子的记录。

参数	类型	必填	说明
id	整数，至少为 1	两者之一	帖子标识符。
url	rule34.xxx 帖子 URL	两者之一	帖子页面的地址。

返回内容： 搜索结果行中包含的帖子信息，以及其完整标签列表。

配置

两个凭据都是必需的。其他所有配置项均为可选，都放在客户端配置的 env 块中。

变量	默认值	说明
RULE34_USER_ID	无，必需	你的数字账号 ID。
RULE34_API_KEY	无，必需	你的个人 API 密钥。
RULE34_USER_AGENT	项目标识	向网站标识你的应用，并提供可联系到相关人员的地址。
RULE34_MIN_INTERVAL_MS	1000	两次请求之间的间隔，范围为 1000 至 60000。
RULE34_TIMEOUT_MS	20000	单次请求的超时时间，范围为 1000 至 120000。
RULE34_MAX_RETRIES	3	临时故障后的重试次数，范围为 0 至 10。
RULE34_CACHE_TTL_MS	300000	答案在内存中的保留时长，范围为 0 至 86400000。
RULE34_CACHE_MAX_ENTRIES	300	同时保留在内存中的答案数量，范围为 0 至 10000。
RULE34_LOG_LEVEL	error	日志级别：silent、error、info 或 debug，写入标准错误流。

凭据的获取方式。 登录后，打开 账户选项，找到名为 API Access Credentials 的一行。该行会显示 &api_key=…&user_id=…，这两个值就是上述配置中需要填写的内容。如果密钥为空，请勾选 Generate New Key? 并保存。

网站为每个人签发一个密钥，并要求展示其内容的应用不得投放广告，也不得设置付费墙。本服务不附带自己的密钥，每位用户都需要提供自己的密钥。未提供凭据时，本服务仍会运行并发布工具，但每次调用都会指出需要设置的两个变量；它不会发送明知会被网站拒绝的请求。

超出取值范围的配置会回退到默认值，并将原因写入标准错误流。

错误

每次失败都会附带以下六种代码之一、一条消息，以及在有帮助时给出下一步提示。

代码	发生了什么	该怎么做
not_found	网站已响应，但该地址没有内容。	使用 search_posts 检查标识符。
invalid_input	请求发出前，参数就被拒绝了。	阅读消息，其中会指出具体参数。缺少凭据也会在此处报告。
rate_limited	网站要求此客户端放慢速度。	等待提示中指出的秒数，然后使用相同参数再次调用。帖子仍然存在。
parse_failure	收到的响应格式无法被此客户端读取。	在问题跟踪器中报告。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	调高 RULE34_TIMEOUT_MS，或减少请求的帖子数量。

作为库使用

读取网站的这一层单独发布，拥有自己的请求间隔、缓存和错误处理，且不附带任何协议。

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);

每次读取都会返回 { data, cached }，并在出错时抛出携带六种代码之一的错误。两次请求之间至少间隔一秒的限制在这里同样适用。

请求间隔与来源说明

请求会逐个发出，且间隔至少一秒，无论服务端如何配置，这个下限都不会改变。User-Agent 的结尾始终包含项目标识和可供联系的地址。

读取操作会访问网站文档中说明的 API，所使用的凭据也是网站条款要求自动读取时使用的凭据。每条结果都包含帖子的页面地址。不会下载任何内容：文件地址会以字符串的形式出现在响应中。

此 MCP 服务是非官方项目，与 rule34.xxx 没有关联。

隐私

此服务不会收集你的任何信息，也不会向其作者发送任何内容。它在你的计算机上运行，只会联系 api.rule34.xxx 和 rule34.xxx，并在运行期间将响应保存在内存中，不会写入磁盘。你的凭据从环境变量中读取，且只会发送给该网站。 PRIVACY.md 说明了请求会携带哪些内容，以及哪些设置会改变这些内容。

开发

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

测试使用生成的固定数据运行，不会发出网络请求。实时测试套件 npm run test:live 会对每个路由发出一次请求，并在每晚针对网站本身运行。

贡献

Bug、问题和想法请提交到 问题跟踪器。欢迎提交 Pull Request；先创建 Issue 有助于商定变更方案。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。帖子和标签归 rule34.xxx 及上传者所有。

---

mcp-rule34（法语）

英文版

rule34.xxx 是一个大型图像论坛，帖子完全按标签编入索引，并提供了供人读取的 API。每个帖子都有自己的 ID、页面和文件地址、尺寸、访客给出的评分、评级，以及其归属的完整标签列表。该网站包含数千万个帖子，并会在按标签搜索时返回找到的数量。

此服务将对话客户端连接到这个索引。可以通过组合必需标签、备选标签和排除标签来搜索帖子；通过 ID 读取帖子详情；还可以在搜索之前确认网站对某个标签的拼写。使用它需要账号和 API 密钥，网站会为每个人分别发放。

安装

Claude Code

claude mcp add rule34 --env RULE34_USER_ID=votre-id --env RULE34_API_KEY=votre-cle -- npx -y mcp-rule34

Claude Desktop、Cursor，以及任何采用标准配置格式的客户端

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

需要 Node 24 或更高版本。两个凭据都是必填项；配置中的其他内容均为可选项。

使用 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 会保持标准输入处于打开状态，它是协议通道；省略 -t 是因为 TTY 会重写数据流。容器需要能够通过 HTTPS 访问 api.rule34.xxx 和 rule34.xxx，并且需要从你的环境中获取这两个凭据：无需卷，也无需端口。

Bundle，无需 npm

从最新版本发布页下载 mcp-rule34-2.0.2.mcpb 并打开。支持 MCP bundle 的客户端会自行安装，无需运行 npm。凭据仍需填入客户端配置。

可以提出的请求

• “网站上这个标签的拼写是什么？”
• “找出带有这两个标签的帖子，并按评分排序。”
• “搜索条件相同，但排除 monochrome。”
• “给我读一下帖子 1234567 的详情。”
• “这个搜索能找到多少个帖子？”

常规流程是先搜索标签，再搜索帖子：find_tags 会返回网站使用的拼写，search_posts 会沿用该拼写。

工具

工具	功能
find_tags	查找标签的拼写，以及带有该标签的帖子数量。
search_posts	按标签搜索帖子，并支持备选标签和排除标签。
get_post	根据帖子 ID 或地址读取帖子详情。

搜索之前请先确认标签。 网站只按标签编入索引，而它不认识的标签不会匹配任何内容；这会显示为空结果，而不是拼写错误。

find_tags

查找标签的拼写。

参数	类型	必填	功能
query	字符串，最多 60 个字符	是	要确认的文本。

返回： 原样返回的 query，以及 tags；每个标签都包含网站使用的拼写和带有该标签的帖子数量。

search_posts

按标签搜索帖子。

参数	类型	必填	作用
tags	1 到 10 个标签名称组成的数组	是	帖子必须带有的标签。
any_of	1 到 10 个标签名称组成的数组	否	帖子必须至少带有其中一个标签。
exclude	1 到 10 个标签名称组成的数组	否	帖子不得带有的标签。
media_type	image、animated、video 或 any，默认值为 any	否	静态图像、GIF 或 MP4。
rating	questionable 或 explicit	否	省略时会搜索两种评级。
sort	score、id、updated 或 random，默认值为 score	否	网站的排序顺序。
limit	整数，1 到 100，默认值为 20	否	返回的帖子数量。
page	整数，1 到 200，默认值为 1	否	帖子所在的页码。

media_type 根据网站本身的标签判断，因此分类是否准确取决于标签本身。网站只知道上述两种评级：其他任何值都会返回零个帖子且不会报错，从而导致结果缺失，而网站实际上并没有缺少这些结果。

返回： 网站拼写形式的 tags、any_of 和 exclude；query，即以网站语言发送的搜索内容；total，即整个搜索找到的帖子数，按网站的计数方式计算；以及帖子本身，每个帖子都包含 id、post_url、file_url、preview_url、sample_url、width、height、score、rating 和 tags。评分来自网站，每天更新一次。

get_post

读取帖子的详情。

参数	类型	必填	作用
id	整数，1 或更大	二选一	帖子的 ID。
url	rule34.xxx 的页面地址	二选一	页面的地址。

返回： 搜索结果行所包含的帖子及其完整标签列表。

配置

这两个标识符都是必填项。其他内容均为可选，全部放在客户端配置的 env 块中。

变量	默认值	作用
RULE34_USER_ID	无，必填	您账户的数字标识符。
RULE34_API_KEY	无，必填	您的 API 密钥，仅供个人使用。
RULE34_USER_AGENT	项目标识	向网站标识您的应用，并提供联系人的联系地址。
RULE34_MIN_INTERVAL_MS	1000	两次请求之间的间隔，范围为 1000 到 60000。
RULE34_TIMEOUT_MS	20000	请求超时时间，范围为 1000 到 120000。
RULE34_MAX_RETRIES	3	临时失败后的重试次数，范围为 0 到 10。
RULE34_CACHE_TTL_MS	300000	响应在内存中的保留时间，范围为 0 到 86400000。
RULE34_CACHE_MAX_ENTRIES	300	同时保存在内存中的响应数量，范围为 0 到 10000。
RULE34_LOG_LEVEL	error	silent、error、info 或 debug，日志写入错误输出。

如何获取标识符。 登录后，打开 账户选项，然后 找到 API Access Credentials 一行。该行会显示 &api_key=…&user_id=…， 这两个值就是上方配置中要填写的内容。如果密钥为空，请勾选 Generate New Key? 并保存。

网站会为每个人发放一个密钥，并要求提供其内容的应用不得展示广告，也不得设置付费墙。 此服务不内置任何密钥，每个人都需要提供自己的密钥。在未配置标识符的情况下启动时， 服务仍会运行并发布其工具；收到每次调用时，它都会指出需要设置的两个变量：它不会发送 任何明知会被网站拒绝的请求。

超出范围的值会回退到默认值，原因会写入错误输出。

错误

每次失败都会带有六种代码之一、一条消息，以及在有帮助时提供的 下一步操作提示。

代码	发生了什么	应该怎么做
not_found	网站已响应，但该地址下没有内容。	使用 search_posts 检查标识符。
invalid_input	在发出任何请求之前，参数就已被拒绝。	阅读消息，其中会指出具体参数。缺少标识符时会在这里提示。
rate_limited	网站要求此客户端放慢速度。	等待指定秒数，然后使用相同参数重试。该发布内容仍然存在。
parse_failure	响应已返回，但其格式无法在此处读取。	在问题跟踪页报告此问题。
network_error	请求未能完成。	稍后重试。
timeout	请求超时。	增大 RULE34_TIMEOUT_MS，或减少请求的发布内容数量。

作为库使用

读取网站的这一层单独发布，带有自己的请求节奏、缓存和错误处理，不附带任何 协议。

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);

每次读取都会返回 { data, cached }，并在出错时抛出带有六种代码之一的错误。 两次请求之间至少间隔一秒的限制在此同样适用。

请求节奏与归属信息

请求会逐个发出，且彼此至少间隔一秒，无论配置如何，此最低间隔都始终 适用。User-Agent 始终以项目身份信息和可联系到相关人员的地址结尾。

读取通过网站文档说明的 API 进行，网站提供的标识符正是其条款要求用于 自动读取的标识符。每条结果都带有发布内容页面的地址。不会下载任何内容： 文件地址在响应中会作为字符串传递。

此 MCP 项目为非官方项目，与 rule34.xxx 无关联。

隐私

此服务不会收集您的任何信息，也不会向其作者发送任何信息。它在您的 机器上运行，只连接 api.rule34.xxx 和 rule34.xxx，在运行期间将响应 保存在内存中，也不会向磁盘写入任何内容。您的标识符会从环境中读取， 并仅发送给此网站。PRIVACY.md说明了请求会携带哪些信息，以及 哪些设置会改变这一情况。

开发

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

测试使用生成的测试样例运行，不会发出任何请求。实时测试套件 npm run test:live 会针对每个路由发出一个请求，并且每晚直接对网站运行。

贡献

欢迎在问题跟踪页报告异常、提出问题 和分享想法。也欢迎提交修改建议；先开一个问题单有助于就修改方案达成 共识。请参阅 CONTRIBUTING.md。

许可证

MIT，详见 LICENSE。发布内容和标签归 rule34.xxx 及提交它们的人员所有。