pixiv-mcp
This server lets an agent search, inspect, and download high-quality Pixiv illustrations with built-in content filtering.
pixiv_search— search Pixiv by character name/tags (multiple tags are AND), auto-filtering AI works, animations, blacklisted/mutually-exclusive tags, and gray-list content unless explicitly allowed; ranks by time-decayed favorites, dedupes per session, applies a cooldown, and downloads original images locally.pixiv_illust_detail— fetch metadata for a PID (title, artist, tags, bookmarks, page count, original URL, rating) and get acompliantverdict using the same rules, without downloading.pixiv_download— download original images for a PID (specific pages orall, up to 10 pages), refusing works that fail the black/gray-list, AI, or animation checks.Content controls —
r18andallow_gray(oral / creampie / paizuri / footjob / ahegao / sex / r18) opt-ins, with R-18 determined by officialxRestrict; gray-list works must genuinely contain the allowed category.Session handling — per-
sessiondedup history and cooldown (default 15s), plus built-in Chinese→Pixiv tag mapping for common character names.Local delivery — returns absolute file paths plus a
caption(🎨 artist) so the calling agent decides how to present images.
Provides tools to search Pixiv illustrations by tags or character names, inspect artwork metadata, and download original images with filtering for blacklisted, gray-listed, AI-generated, animated, and R-18 content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pixiv-mcp search Pixiv for 信濃 水着 and download 2 illustrations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pixiv-mcp
独立的 Pixiv 插画搜索 / 过滤 / 下载工具,提供三种用法:
MCP server(stdio):给 Codex CLI、Claude Desktop / Claude Code、Cursor、Grok Bot 等任意支持 MCP 的 agent 用
CLI:
pixiv-mcp search 信浓 泳装 2,方便测试,也给不支持 MCP 的 agent 用TypeScript 库:
import { PixivService, pixivSearch } from 'pixiv-mcp'
它是从 QQ bot 插件(dsh-qqbot 的 src/pixiv)里拆出来的,过滤规则一条没改,不依赖 QQ bot、cordis/cosmokit、antigravity、会话或传输层。规则细节见 pixiv-feature-spec.md。
运行时依赖只有 @modelcontextprotocol/sdk 和 zod。网络请求用 Node 自带的 fetch,不处理图片、不用浏览器。
安装
需要 Node.js ≥ 20.3(推荐 22 或 24)。
发布包里已经带了编译好的 dist/,服务器上不需要 TypeScript 或 vitest:
tar xzf pixiv-mcp.tgz && cd pixiv-mcp
npm ci --omit=dev # 只装运行时依赖(约 26 MB)
node dist/bin.js --help开发 / 改代码:
npm ci
npm run build # tsc → dist/,bin 入口为 dist/bin.js
npm test # 会先 build,再跑 vitest(含 stdio 端到端测试)
npm run typecheck想要全局命令 pixiv-mcp 时,在目录里执行 npm link 或 npm i -g .。
低内存启动(2 vCPU / 1 GB 机器)
node --max-old-space-size=96 --max-semi-space-size=1 dist/bin.js serve实测(Linux,Node 24,接本地模拟的 Pixiv):
启动参数 | 空闲 RSS | 跑 20 轮搜索+下载后 RSS(峰值) |
| 77 MB | 105 MB(107) |
| 69 MB | 94 MB(100) |
再加 | 59 MB | 68 MB(70),但速度慢很多,不推荐 |
光是加载官方 MCP SDK 的 stdio 部分(它会带上 zod 协议 schema)就要约 64 MB RSS,裸 Node 约 41 MB,所以用官方 SDK 时 60 MB 以下基本做不到。原图下载是流式写盘的,不会把整张图读进内存。
Related MCP server: ZeroChan MCP
环境变量
变量 | 说明 |
| Pixiv refresh token。配了且没设 |
| 网页登录态,加到网页 AJAX 请求的 Cookie 上 |
|
|
| 数据目录,默认 |
| 图片目录,默认 |
| 每个 session 的冷却,默认 |
| 全局同时下载数,默认 |
| 单张原图上限,默认 |
| 本地图片缓存上限,超出按最久未用淘汰,默认 |
| 单次请求超时,默认 |
| 可选:把没映射的中文词交给 OpenAI 兼容模型翻成 Pixiv 标签 |
| 上一项用到的接口,如 |
| 需要走 HTTP 代理时用(Node ≥ 24 的原生 fetch 支持),图片下载同样走代理 |
LLM 不是必须的。 推荐让调用方 agent 自己把中文描述翻成 Pixiv 常用日文标签再传进来(比如 水手服→セーラー服)。内置的中文角色映射表照样生效,没映射的词按原样当标签用。
怎么拿 refresh token
Pixiv 没有官方开发者入口,refresh token 只能从官方 App 的 OAuth 登录流程里拿:
gppt(最省事,会开一个浏览器让你登录):
pip install gppt,然后运行gppt login-interactive(或gppt login -u 邮箱 -p 密码),输出里的refresh_token就是。pixiv_auth.py(ZipFile 的 gist,“Retrieving Auth Token (with Selenium)”那篇):运行
python pixiv_auth.py login,在浏览器里登录,再按说明从开发者工具的网络面板里复制code,脚本会换出refresh_token。
拿到之后填进 PIXIV_REFRESH_TOKEN。它长期有效,本工具会自动换 access token 并缓存。token 失效时自动退回网页搜索,日志写到 stderr。
MCP 工具
工具 | 作用 |
| 搜索并下载。参数: |
| 按 PID 读元数据,并用同一套规则给出 |
| 按 PID 下载原图( |
返回 JSON 里的字段:localPath / files[].path 是本地绝对路径,caption(🎨 画师:xxx)给 agent 展示用,url 是作品页地址。
过滤规则和 bot 版完全一致:
多标签 AND
互斥组蹭标签、AI(
aiType=2)、动图、黑名单直接丢;请求里出现黑名单词就整次拒绝,而且不扣冷却。短英文关键词(如bl)以及腐、グロ只按整词匹配灰名单默认避开;显式放行的类别作品必须真有
R-18 只认官方
xRestrict综合分 = 真实收藏数 × 1 年半衰期;同一 session 不重复出图,看完一轮自动重新循环
搜索按
10000users入り→ … → 纯标签逐档降级,每档最多翻 2 页;档位按真实收藏数算(users入り标签有人乱打)综合分低于下限的作品(老图、低收藏图)只在凑不够数时补位
429 / 5xx 指数退避重试
可选环境变量:
PIXIV_GREY_POLICY=deny:这个 MCP 进程彻底拒绝灰名单(r18/allow_gray,或把 r18 之类的词写进tags,一律blocked)。给受限环境用;开关在进程环境里,模型改不了。PIXIV_SAFE_FILTER=1:恢复旧行为,搜索时带 Pixiv 的for_ios安全过滤(默认不带,它会把标记为"敏感"的全年龄图也滤掉;官方 R-18 仍由本地xRestrict拦截)。PIXIV_HISTORY_FILE:已发 PID 记录的文件位置(默认$PIXIV_MCP_HOME/pixiv_history.json)。多个进程(比如机器人和它启动的多个 MCP)指向同一个文件,就能共用去重记录。PIXIV_PREFS_FILE:按 session 的找图偏好(默认$PIXIV_MCP_HOME/pixiv_prefs.json)。由调用方写(比如 QQ 机器人记录用户对图的「喜欢 / 不喜欢 / 拉黑画师」),本服务只读、按修改时间自动重新加载:拉黑的画师和作品不再出现,其余候选按偏好调整先后,搜索词本身不参与计算,也不放宽任何黑/灰名单。写入接口见src/core/prefs.ts的PixivPrefsStore。PIXIV_TIER_PAGES(默认 2):每个质量档最多翻几页,每页 30 条。PIXIV_MIN_SCORE(默认 100):「够好」的综合分下限。PIXIV_LOCAL_SHORTCUT_SCORE(默认 1500):本地缓存里够数的候选综合分都达到它,才不联网直接从缓存发图。
词典
内置词典(
src/core/constants.ts):CHARACTER_TAG_MAP是中文角色名 → Pixiv 标签,共 448 条,覆盖碧蓝航线、原神、星穹铁道、明日方舟、蔚蓝档案、赛马娘、VOCALOID、hololive 及常见番剧;COMMON_ATTR_MAP是常见服饰/属性词。蔚蓝档案按 SchaleDB 官方译名和 Pixiv 实际标签整理,只收全名,去掉了和其它作品撞名的短名(例如「明日奈」交给 SAO 亚丝娜)。人工词典优先于自学习表。自学习词典种子(
data/pixiv_dynamic_tags.seed.json,392 条):运行中学到、并经 Pixiv 自动补全校验过的映射。已去掉和内置词典重复的、映射到自己的,以及已知的坏映射。想让新装的实例直接用上,首次启动前复制过去:mkdir -p ~/.pixiv-mcp && cp data/pixiv_dynamic_tags.seed.json ~/.pixiv-mcp/pixiv_dynamic_tags.json
1.1.0 更新
单次张数上限 3 → 5,与 QQ bot 端用同一个常量。
新增
tag-oracle:LLM 只提标签候选,必须经 Pixiv 自动补全和搜索命中校验后才写入动态表、才用于检索。新增复合词拆解(
compound):「巨乳妃咲」这类属性词 + 角色名粘连的输入能拆开;体型/发型等特征词用本地词典,不交给 LLM。作品名前缀剥离(「碧蓝航线帝国」→ 帝国);角色词典扩充。
已发 PID 历史支持多进程共用同一个文件(按 mtime 合并);
c2c:<id>/group:<id>会话键与 QQ bot 软路由共用去重历史。0 结果时的纠错模式(错别字、角色名、汉字纠正)。
降噪成品图跟随原图一起淘汰,不留孤儿文件。
MCP 工具说明里写明出图格式:只给图片和
🎨 画师:xxx,标签和 r18 只取本条消息明确写出的。搜图质量:收藏数用真实值(不再把未知收藏数抬到档位门槛),档位按真实收藏数算;每档翻页;综合分下限;本地缓存只在足够好时直出,否则和网上的新候选一起比较。
「死库水 / 学校泳衣 / スク水」等映射到主流标签
スクール水着(中文标签「死库水」只有少量 2016–2017 年的老图)。新增自学习词典种子
data/pixiv_dynamic_tags.seed.json。人工词典(角色别名、常见属性词)优先于自学习动态表,避免学到的坏映射(如 女仆→ノエル)覆盖正确值;角色词典与 QQ bot 同步(含蔚蓝档案全名,去掉了与其它作品撞名的短名)。
各客户端配置
下面示例用相对路径 ./dist/bin.js(先 cd 到项目根目录再启动)。若写成绝对路径,Windows / Linux / macOS 各自换成你的实际路径即可。
Codex CLI:~/.codex/config.toml(Windows:C:\Users\<你>\.codex\config.toml)
[mcp_servers.pixiv]
command = "node"
args = ['--max-old-space-size=96', './dist/bin.js', 'serve']
startup_timeout_sec = 20
tool_timeout_sec = 120
[mcp_servers.pixiv.env]
PIXIV_REFRESH_TOKEN = "你的token"
PIXIV_MCP_HOME = '~/.pixiv-mcp'TOML 里用单引号字符串,Windows 反斜杠就不用转义。
Claude Desktop:%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"pixiv": {
"command": "node",
"args": ["--max-old-space-size=96", "./dist/bin.js", "serve"],
"env": {
"PIXIV_REFRESH_TOKEN": "你的token",
"PIXIV_MCP_HOME": "~/.pixiv-mcp"
}
}
}
}Claude Code
claude mcp add pixiv -s user -e PIXIV_REFRESH_TOKEN=你的token -e "PIXIV_MCP_HOME=~/.pixiv-mcp" -- node --max-old-space-size=96 "./dist/bin.js" serveCursor:~/.cursor/mcp.json(全局)或项目里的 .cursor/mcp.json
内容和 Claude Desktop 那段 mcpServers 一样。
Grok Bot(本地 stdio MCP)
在 Grok Bot 添加本地 MCP 时填:
命令:
node参数:
--max-old-space-size=96、./dist/bin.js、serve环境变量:
PIXIV_REFRESH_TOKEN,以及可选的PIXIV_MCP_HOME
如果要求填 JSON,就用和 Claude Desktop 一样的 mcpServers.pixiv 那段。
不支持 MCP 的 agent:直接调 CLI
node dist/bin.js search 信浓 泳装 2 --json
node dist/bin.js search --tags "オリジナル 水着" --gray oral --session alice
node dist/bin.js detail 12345678 --json
node dist/bin.js download 12345678 --pages all --json退出码:成功为 0;失败、被拦截或冷却中为 1;用法错误为 2。
和 bot 版的差别
数据目录从
~/.dsh-qqbot改为~/.pixiv-mcp(可用PIXIV_MCP_HOME改)LLM 补标签从“拉起本机 agy”改为可选的 OpenAI 兼容接口(默认关闭)
新增
pixiv_illust_detail/pixiv_download(按 PID),规则复用同一套过滤网络失败、连续失败熔断时,结果里带
notice说明原因,不再静默返回空下载改为流式写盘,加了全局并发上限和单图大小上限;本地缓存上限默认从 2 GB 改为 512 MB
不负责发送图片:工具返回本地路径和 caption,由 agent 决定怎么展示。多图间隔 1.5 秒属于 QQ 发图的限制,这里不需要
Available Tools
3 toolspixiv_downloadPixiv 原图下载A
按 PID 下载原图到本地目录(PIXIV_MEDIA_DIR),返回每页的文件绝对路径与作品元数据。不合规(黑名单/未放行的灰名单/AI/动图)的作品拒绝下载。最多 10 页,下载并发受 PIXIV_DOWNLOAD_CONCURRENCY 限制。
Inputs: pid (required), r18, pages, allow_gray.
pixiv_illust_detailPixiv 作品详情A
按 PID 读取作品元数据(标题、画师、标签、收藏、页数、原图地址、分级),并按同一套黑/灰名单规则给出 compliant 结论。不下载。
Inputs: pid (required), r18, allow_gray.
pixiv_searchPixiv 插画搜索A
按角色名/标签搜索 Pixiv 高质量插画,下载原图到本地并返回文件路径与元数据。多个标签是 AND(全部要在作品标签或标题里命中)。自动过滤:同作品互斥角色蹭标签、AI 生成(aiType=2)、动图、黑名单(BL/猎奇/福瑞/抽象整活等,请求里含黑名单词会被整次拒绝)。灰名单(R-18 及特定玩法)默认避开,只有 r18 / allow_gray 明确放行时才放行且必须真有。R-18 只认 Pixiv 官方 xRestrict。按 1 年半衰期收藏数排序,同一 session 不重复出图;同一 session 有冷却(默认 15 秒)。中文角色名有内置映射;不在映射里的词建议调用方先翻成 Pixiv 常用日文标签再传入(如 水手服→セーラー服)。给用户展示时,输出内容只能有图片和 caption(🎨 画师:xxx):禁止附带作品标题、PID、Pixiv 链接、file:// 链接、本地路径或任何说明文字。tags 只能取自用户本条消息明确写出的词,r18 / allow_gray 仅当本条消息明文要求时才设置,不得从历史对话继承。
Inputs: tags (required), r18, count, session, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Search (by tags/character), download (by PID), and detail (by PID) have mostly distinct entry points, and descriptions make the download-vs-detail split clear. However, search also returns metadata and file paths, overlapping somewhat with the other two, so an agent may occasionally pick search when it really wants a direct PID fetch.
All tools share a consistent `pixiv_` prefix, but the suffixes mix verbs (`search`, `download`) with a noun phrase (`illust_detail`). Still readable and predictable in practice, just not a uniform verb_noun pattern.
Three tools is on the thin side for a Pixiv illustration workflow, though each has a clear role (search, fetch by PID, download by PID). It is borderline minimal rather than obviously under-scoped.
Core flows—search by tag, inspect by PID, download by PID—are covered with consistent filtering semantics. Notable gaps remain: no way to list or browse an artist's works, no ranking/related/tag-suggestion lookup, and no session or blacklist management operations.
Maintenance
Related MCP Connectors
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Browse, search, upload, tag, transfer, and delete images in your Raster libraries over MCP.
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables browsing, searching, and downloading Pixiv content including illustrations, rankings, recommendations, and user bookmarks. Supports intelligent batch downloads with automatic Ugoira-to-GIF conversion and OAuth 2.0 authentication.5MIT
- AlicenseAqualityDmaintenanceMCP server for the Zerochan anime image board API. Browse the global feed, search by tags, and retrieve full entry metadata — directly from any MCP-compatible AI assistant.3MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to search and browse manga, inspect album details, comments and rankings, manage favorites, and download albums, chapters, and covers with progress reporting, cancellation, retry, and batch task control. Also supports post-processing downloads into ZIP, PDF, or long images and dynamic runtime configuration, exposed as MCP tools and knowledge resources over stdio, SSE, and HTTP transports.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to search, browse, and download comics via natural language, manage favorites, read comments and rankings, and convert downloaded content into ZIP, PDF, or long images. It also exposes download planning, background task progress, cancellation, retry, login/session handling, and runtime configuration as MCP tools and resources.-