Skip to main content
Glama

eh-mcp

给 agent 用的 e-hentai / exhentai MCP server(stdio,纯 ESM,无构建)。

工具面三层:契约里定死的 25 个核心工具 + 从 Ehviewer_CN_SXJ 真实实现里移植的 9 个扩展(含 eh_download_cancel)+ 5 个一步到位的复合工具(eh_find / eh_open / eh_read / eh_quick / eh_image_search),共 39 个。

输出默认按 agent 习惯压缩(默认字段集、limit=10、format="tsv" 可选),真实调用示例与 token 数见 docs/agent-usage.md。


功能一览

配置与登录

工具

用途

eh_config_get

读配置(cookie 只回名字与数量,不回值)

eh_config_set

改配置并落盘(深合并)

eh_login

账号密码登录,拿 ipb_member_id / ipb_pass_hash / igneous

eh_cookie_set

直接导入 cookie 串或键值对象

eh_cookie_status

看 cookie 是否有效、登录的是谁、实际能走哪个站

eh_site_switch

在 e-hentai / exhentai / auto 之间切

浏览与搜索

工具

用途

eh_search

主力搜索:mode=search/uploader/tag/watched,支持分类掩码与高级搜索

eh_gallery

画廊详情(标题、tag、评分、归档、种子)

eh_popular

热门:默认走 /popular 通栏页;传 period 走 toplist.php(除 all 外需登录)

eh_recent

首页最新

eh_watched

我的画廊(需登录)

eh_favorites

收藏夹(cat=0..9 / favdel)

eh_fav_add

加收藏到指定槽位

看图与下载

工具

用途

eh_pages

列多页查看器链接(支持 from/to 区间)

eh_image

解析看图页 → 真图片地址(含 showkey/重载)

eh_thumb

直接回图片二进制给模型看(自动带 cookie + Referer)

eh_download

整本下载(并发 + 断点续传 + 短包校验)

eh_download_status

看本进程内下载进度(running / cancelling / done / cancelled / failed)

eh_download_cancel

取消正在跑的下载(已下完的保留,meta 标 cancelled,下次可续)

eh_archive

归档信息 / 下归档(GP)

订阅、历史与 tag

工具

用途

eh_sub_add / eh_sub_list / eh_sub_remove / eh_sub_check

搜索式订阅:存下来、列出、删除、只拉新作品

eh_history

本地历史(浏览 / 搜索 / 下载)

eh_tags

tag 补全(本地字典优先:中文可直接联想,如 巨乳 → female:big breasts)

本地标签字典来自 EhTagTranslation/Database,编译产物 src/tags-db.json 随仓库走,运行时只读不联网。口语说法(中文 / 汉化 / 无码 / NTR / 黑丝…)走手写的 src/tags-alias.json,目标 tag 在载入时校验,不存在的条目会被跳过。库里变动时重建一次:

node scripts/build-tags.mjs        # 走 socks5://127.0.0.1:10808,12 个命名空间,约 4.5 万条;顺带校验别名表
node test/_t_tags.mjs              # 离线验证,期望 PASS n/0

收藏夹与本地库

工具

用途

eh_favorites

收藏夹列表(cat=0~9/all/favdel),query 走站点内搜(f_search+sn/st/sf),cache=true 把这页存进本地缓存

eh_fav_local

断网可用:搜已缓存收藏,支持 title: tags: note: gid: cat: 前缀

eh_local_index

扫下载目录建索引(action=rebuild 增量 / stats 看统计)

eh_local_search

在下好的画廊里搜:裸关键词、ns:value(f:big breasts 与 female:"big breasts" 等价)、/正则/、tag:/re/、-排除、`

本地索引落在 ~/.dsh-eh/library.json(≈512 B/条,500 条约 250 KB)。增量判据是目录 + meta.json 的 mtime/size:500 条首次约 450 ms、二次增量约 130 ms、单次查询约 0.6 ms。下载落盘的 meta.json(v2)里 gallery 块含 title/titleJpn/uploader/tags/site/category,所以 tag 与作者都能搜;老目录缺这块就搜不到 tag,重下一次即可。

本地面板(DSH-EH)

只读的本地浏览面板,跟 MCP 进程分开跑:node panel/server.mjs --port 7712(只绑 127.0.0.1,端口被占自动顺延,最多 +10,启动后打印真实地址;--data / --root 可换数据目录与下载根)。 数据只读 ~/.dsh-eh/ 下的 history.jsonl(浏览/下载/搜索记录)、notes.json(笔记)、library.json(本地库索引),封面图从下载根目录(默认 ~/.dsh/eh-downloads)取,越界路径一律 403。

DSH 里点侧边栏的 DSH-EH 就能在窗口内打开它(dsh-eh-panel 插件注册的 main 面板,iframe 嵌 7712,服务没起会自动拉起)。

配色跟着 DSH 本体走:内嵌时由 dsh-eh-panel 把 8 个颜色变量(--eh-bg / -bg-elev / -bg-hover / -border / -text / -text-dim / -accent / -accent-dim)从 DSH 的真实 token 里取出来 postMessage 下发,mode 取自 body[data-ds-dark-theme];切主题即时生效。单独用浏览器打开时按 prefers-color-scheme 自己判断。 面板现在分三组:浏览(主页 / 热门 / 收藏 / 订阅 / 搜索)、本地(看过 / 下载 / 笔记 / 本地库)、设置(账号与配置)。浏览类页面直接复用 MCP 的 cookie 与限速,卡片上带站点原样的 category 角标(叙事类 / 差分类 / 真人各一色,Misc、Non-H 带 hover 说明)。

账号与配置页可以做账号密码登录、粘贴 cookie、切站点、改代理 / 下载目录 / 账号分层 / 并发与限速;cookie 只显示键名与长度,写盘后 MCP 下次调用自动生效。 阅读器在面板里,不再跳浏览器:本地有下载就优先读本地文件,没有就走在线(panel/online.mjs 复用同一份 config / cookie / 代理 / 解析器,20 页一个窗口懒加载)。← → 翻页、Home/End 首尾、Esc 回详情、宽屏可双页;顶部只有「在源站打开 ↗」一个出口会交给系统浏览器。

分类与阅读策略(agent 必读)

站点只有 11 个分类,category 字段在搜索、列表、eh_gallery、eh_download、历史、本地库搜索里都会带出来,值就是站点原样写法:

分类

内容特点

建议的读法

Doujinshi

同人志,连续分镜叙事

逐页读(eh_pages 全量 or 分段 20)

Manga

商业志/连载,同样连续

逐页读

Artist CG

画师图集,大量近似差分

跳页读:先看 1、中间、最后,再抽查

Game CG

游戏 CG 抽出,差分多

跳页读

Image Set

图集/合集,顺序常无叙事

跳页读

Cosplay

真人照片

跳页读,除非要找特定造型

Asian Porn

真人照片/影像截图

跳页读

Western

欧美同人/图集,质量参差

先看标题与页数,再决定逐页或跳页

Non-H

非成人内容

非本任务目标时直接跳过

Misc

AI 生成居多、杂项

默认可跳过,除非标题明确相关

Unknown

站点没标

看标题/页数判断

跳页读的具体做法:eh_pages { gid, token, from: 1, to: 3 } 看开头,再取中间与结尾各 2~3 页;确认是同一套构图就停,别为了一张差分把整本翻完。

eh_download 返回里也带 category,历史记录同样有,所以「下过什么、属于哪类」是可以离线检索的。

评论与笔记

工具

用途

eh_comments

读这本的在线评论:作者、时间、评分、正文(full=true 连带投票明细)。没下载过也能读,走详情页 #cdiv

eh_note_save

写感想:note 必填,可选 rating(1~10) / tags / source(online/local) / title / token

eh_note_list

列 / 搜笔记(query 匹配标题、正文、tag),新的在前

eh_note_remove

删笔记(按 gid)

eh_comments 读过的评论会缓存到 ~/.dsh-eh/comments.json(每本留最新一份),面板断网也能看。

笔记存在 ~/.dsh-eh/notes.json,线上看的和下载后看的是同一份,按 gid 对齐,所以面板里一本只会有一条。看完一本顺手记一句,比攒着写长评实际。

另外,任何一次成功打开详情页(eh_gallery / eh_open / eh_read / 下载前的元数据补全)都会往 ~/.dsh-eh/history.jsonl 记一条 type:'view',这就是「agent 看过什么」的数据源。

移植自参考仓库的扩展

工具

来源

用途

eh_toplists

toplist.php

排行榜,tl + 翻页 p(0~199)。未登录只有 tl=all 能用,其余周期站点直接回 “Non-existing toplist”

eh_uploader

/uploader/<名字>

某个上传者的全部作品

eh_tag_page

/tag/<tag>

站点原生 tag 页,比 f_search 更接近点 tag 链接

eh_batch_meta

api.php → gdata

一次最多 25 个 gid+token,批量补标题/tag/评分/体积/种子数

eh_mytags

/mytags

站点记录的「我用过的 tag」,需登录

eh_filter_list / eh_filter_add / eh_filter_remove

EhFilter

本地标题/tag/上传者黑名单;eh_search 带 filter=true 时生效


Related MCP server: jmcomic-ai

给 agent 的省 token 用法(先看这节)

列表类工具默认为 4 个字段 / 10 条 / 不带 url·thumb·tagsPreview。要更多再加参数:

参数

作用

默认

fields

逗号分隔要回的字段,如 "gid,title,pages,rating"

gid,token,title,pages(eh_find 多 category)

format

json(紧凑无缩进)/ tsv(首行表头,一行一条)

json

limit

返回条数

10(最大 50)

offset

跳过前 N 条;hasMore=true 时 body 里有 nextOffset

0

返回体统一成 {tool, site, count, hasMore, items}:site 是这次实际生效的站点(exhentai / e-hentai), 不是配置里的 auto。null / 空串 / 空数组字段直接不出现,warnings 只在非空时出现。 url 不回——gid + token 就能拼 {site}/g/<gid>/<token>/。

一步到位

工具

一次调用干完什么

什么时候用

eh_quick

登录状态 + 首页最新 5 条 + 订阅新作

会话开场

eh_find

搜索 + gdata 批量补全 → 精简列表

找本第一步

eh_open

详情 + 前 N 页图片直链

要下载/看图前

eh_read

详情 + 封面与前几页真图(image content)

想先看看内容

eh_image_search

以图搜图(path 本地 / url 远程,multipart 上传)

手上有图没出处

省 token 的典型组合(省掉 2~3 次往返):

eh_quick {}                                 → 三合一,≈180~420 token
eh_find  {query, limit:10, format:"tsv"}    → 10 条,≈385 token(JSON 同内容 ≈570)
eh_open  {gid, token, pages:3}              → 详情 + 3 条直链,≈205 token
eh_gallery {gid, token}                     → 精简元数据,≈70 token(full:true 才有完整 tag/警告)

高级搜索(对齐手机端面板)

eh_search 的 adv 用站内真实字段,出现任意一项就自动带 advsearch=1:

name→f_sname  tags→f_stags  desc→f_sdesc  torrentName→f_storr  withTorrents→f_sto
expunged→f_sh lowPower→f_sdt1 downvoted→f_sdt2
disableLang→f_sfl disableUploader→f_sfu disableTags→f_sft
minRating→f_sr+f_srdd(1..5)   pageFrom/pageTo→f_sp+f_spf/f_spt

旧名 torr/del/exp/lang/uploader/fav 仍收(映射到同一批字段)。category 十项走 toFCats 取反: doujinshi / manga / artistcg / gamecg / western / nonh / imageset / cosplay / asianporn / misc。


安装

cd D:/DSHQQ/eh-mcp
npm install          # 依赖已锁在 package-lock.json
node test/smoke.mjs       # 离线冒烟:39/39 工具 + URL 构造 + 过滤规则往返
node test/_t_compact.mjs  # 离线:字段裁剪 / tsv / limit·offset / 空值省略 / 复合工具

依赖:@modelcontextprotocol/sdk、cheerio、undici、socks-proxy-agent。

要求 Node ≥ 20(实测 v23.10.0),项目是纯 ESM("type": "module"),没有 TS 构建步骤。


配置:~/.dsh-eh/config.json

eh_config_set 就是写这个文件;手改也行,下次调用自动读到。

字段

默认

说明

site

"auto"

auto / e-hentai / exhentai。auto 会探测 exhentai 是否可用(结果缓存 5 分钟)

proxy

"socks5://127.0.0.1:10808"

支持 socks5://、socks4://、http://;空串 = 直连

cookies

{}

键值对象,登录/导入后自动填;常用键 ipb_member_id、ipb_pass_hash、igneous

downloadDir

~/.dsh/eh-downloads(Windows:C:\Users\<用户名>\.dsh\eh-downloads)

下载根目录,每本一个子目录

accountScoped

true

按账号分子目录:exh-<memberId> / eh-<memberId> / anon;关掉就全部平铺在 downloadDir 下

concurrency

4

下载并发(1~16)

rateLimitMs

800

每次请求最小间隔,调小容易被 ban

userAgent

桌面 Chrome

站点对移动端 UA 用另一套页面结构,别乱改

dataDir

~/.dsh-eh

历史/搜索/订阅 JSON 的目录

最小可用配置:

{
  "site": "auto",
  "proxy": "socks5://127.0.0.1:10808",
  "cookies": {},
  "downloadDir": "~/.dsh/eh-downloads",
  "accountScoped": true,
  "concurrency": 4,
  "rateLimitMs": 800
}

登录:两种姿势

姿势一:账号密码(推荐首次用)

eh_login { username, password }

走 https://forums.e-hentai.org/index.php?act=Login&CODE=01,成功后把 ipb_member_id / ipb_pass_hash / session_id 存进配置;再访问一次 exhentai 拿 igneous。

eh_cookie_set { cookieString: "ipb_member_id=xxx; ipb_pass_hash=yyy; igneous=zzz" }

浏览器 F12 → Application → Cookies,把 e-hentai(或 exhentai)域下的这三个键抄过来即可。键值对象形式也收:

eh_cookie_set { cookies: { ipb_member_id: "xxx", ipb_pass_hash: "yyy", igneous: "zzz" } }

验证:eh_cookie_status → 看 loggedIn 与 site。site 是 e-hentai 说明 exhentai 还进不去(多半缺 igneous)。


在 DSH 里注册

mcp_connector_configure {
  "name": "eh-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["D:/DSHQQ/eh-mcp/src/index.js"]
}

注册后工具名会带前缀(如 mcp__eh-mcp__eh_search),直接对 agent 说「搜 xxx 的本子」就会命中。

启动时 stderr 会打一行 [eh-mcp] v0.2.0 已启动 · 工具 39/39 个 · node v23.10.0,以及任何缺失模块的警告。stdout 只走 MCP 协议,不掺日志。


移植自参考仓库的能力

src/reference-notes.md 是从 Ehviewer_CN_SXJ 的 com.hippo.ehviewer.client 里逐条抠出来的真实实现,落地成下面这些:

  1. 列表 URL 构造(ListUrlBuilder 等价物)—— eh_search 的 mode / category / adv 全部映射到站点的真实参数:

    • 搜索:?f_search=<enc>&page=<n>&f_cats=<(~cats)&1023>

    • 上传者:/uploader/<enc name>[/<page>]

    • tag:/tag/<enc tag>[/<page>]

    • 高级搜索:advsearch=1 + f_sname/f_stags/f_sdesc/f_storr/f_sto/f_sh/f_sfl/f_sfu/f_sft、f_sr+f_srdd、f_sp+f_spf/f_spt

    • 分类掩码是取反语义(f_cats = (~cats) & ALL_CATEGORY,ALL_CATEGORY = 1023):传进来的 category 是「想看哪些」,出门时取反。

  2. gdata 批量元数据 —— eh_batch_meta POST api.php,{"method":"gdata","gidlist":[[gid,token],...],"namespace":1},每批上限 25 条。

  3. 归档三步 —— eh_archive 的 info 只读 /archiver.php,request 才会真下单(耗 GP)。

  4. 登录三件套 —— ipb_member_id / ipb_pass_hash / igneous,缺 igneous 时 exhentai 一律 302 回 e-hentai。

  5. 排行榜 / 我的 tag / 上传者页 —— eh_toplists、eh_mytags、eh_uploader、eh_tag_page。

  6. 本地过滤(EhFilter) —— eh_filter_* 存 ~/.dsh-eh/filters.json(原子写),eh_search 的 filter=true 在结果上做标题/tag/上传者的子串剔除。

参考仓库里自己的 CBOR spider 后端没有照搬——我们只走标准 HTTP。


常见坑

  • exhentai 必须要有 igneous。只给 ipb_member_id + ipb_pass_hash 时,exhentai 会 302 回 e-hentai;eh_cookie_status 的 site 会显示 e-hentai,别以为是登录失败。

  • 图片必须带 Referer。缩略图/大图都按 Referer 防盗链,eh_thumb 默认补站点首页;自己写请求时别漏。

  • GP 归档要先看价格。eh_archive action=request 会真花 GP,先 action=info 看清再下单;没 GP 时站点只给 H@H 提示。

  • IP ban。短时间内大量请求会拿到 temporarily banned,本 server 会识别成 EHBlocked 并回一句人话。等 10~30 分钟,或换代理;rateLimitMs 调到 1200+ 更稳。

  • exhentai 有里站专属内容,但它对 cookie 更挑;site=auto 探测失败会自动回落到 e-hentai,不会整个工具挂掉。

  • 看图是两跳:先 eh_pages 拿 /s/<ihash>/<token>-<n>,再 eh_image 才换成真图片地址。直接对 /g/ 详情页调 eh_image 解不出东西。

  • 排行榜的 4h/1d/1w/1m/1y 需要登录。没登录时站点返回 “Non-existing toplist”,本 server 会翻成一句人话并提示改用 tl=all。

  • 排行榜 / /popular 不是网格布局。它们是通栏表格页,没有 .gl1t,eh_toplists/eh_popular 在常规解析为空时按 /g/<gid>/<token>/ 链接兜底抽取,标题取自链接文本(<div class="tun"><a>标题</a></div>);这类页面的分类/缩略图/页数仍为空,需要细节就再对单个 gid 调 eh_batch_meta 或 eh_gallery。

  • eh_download 的进度只在本进程内。MCP server 重启后 eh_download_status 会空,但文件还在:断点续传按 meta.json(v2)里记的字节数判断——大小对得上才算下完,被截断的会重下。没有 meta 的老目录退化为「非空即跳过」。

  • 下载会自查三件事:content-length 与实际字节(短包重试 3 次后进 failed.json,不拖累其它图)、目标盘剩余空间(<200MB 直接拒绝)、429 / temporarily banned(并发临时减半 + 退避 5s,写进 warnings)。


语义约定(踩过坑,写在前面)

  1. category 是「想要哪些分类」,不是站点原生的 f_cats。内部按参考实现取反:f_cats = ALL_CATEGORY(1023) & ~want。传 "doujinshi" / "doujinshi,manga" / 位掩码都行。

  2. 列表页的 pages 可能为 null:站点只在部分行渲染 N pages,且上传者昵称尾部的数字会粘上来(TMDlixin250 + 37 pages → 曾误解析成 25037)。解析器已用左边界断言修掉,拿不到就老实返回 null,要准确页数用 eh_batch_meta / eh_gallery。

  3. eh_pages / 下载在页数未知时会一直翻到最后一屏(空屏或不足 20 条即停),不会只拿第一页。

  4. eh_download 的并发/续传:文件名 001.webp 递增,已存在且非空即跳过;meta.json 记下每张图的源 URL,failed.json 记失败项。

  5. eh_archive action=request 才下单(默认 dryRun 只在 info 生效),另外 request 会真的消耗 GP。

已验证(真机、走 SOCKS5 代理)

  • 搜索 25 条 / 详情解析(标题·页数·体积·评分·tag·归档链接)/ 多页链接 / 图片直链(185 字符带 keystamp,780×1200)

  • batchMeta(api.php gdata)批量补全:体积、发布时间、tag(ns:value 数组)

  • 完整下载 13 张(并发 3、0 失败),断点续传与 meta.json 落盘正常

  • eh_toplists(tl=all) 37 条、eh_popular 71 条、eh_thumb 返回 image/webp

  • 二进制通道:client.getBinary()(http.js 已内置),eh_thumb / 下载共用同一条代理链路

  • 收藏夹:eh_favorites(cat=0) 列表 / query 站内搜(takoro 命中 1)/ cache=true 落缓存 → eh_fav_local 断网搜(pixiv 命中 3)

  • 本地库:下载落 C:\Users\deepd\.dsh\eh-downloads\exh-6829692\4317228-0a20c864cf(11 张,meta 含 30 个 tag),eh_local_search 支持 female:big breasts(未加引号也能并)、f:big breasts、character:astra yao、/pixiv|短篇/

  • 全套测试:smoke 46/46、_t_core / _t_local 56 / _t_fav 38 / _t_dl 78 / _t_dl2 58 / _t_tags 36 / _t_comments 11 / _t_auth2 / _t_compact 全绿

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server for E-Hentai and ExHentai, enabling gallery search, metadata retrieval, similar-gallery lookup, tag resolution, and authenticated favorites/archive access.
      30
      20 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      This MCP server exposes 21 tools and 3 resources that enable AI clients to search, browse, and download JMComic albums and photos, manage favorites, fetch comments, update configuration, and perform post-processing like ZIP/PDF export over stdio, SSE, or HTTP transports.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes 21 tools and 3 knowledge resources so AI agents can search, browse, and download albums, manage favorites and comments, query rankings, and convert downloaded content into ZIP, PDF, or long images, with background task control and retry support. It supports stdio, SSE, and HTTP transports alongside runtime configuration updates and account login with cookie persistence.
      -