JMComic MCP Server

把 jmcomic（禁漫天堂 Python API）包装成 MCP 工具，让支持 MCP 的客户端 （Claude Desktop / Cherry Studio / Cursor / 自建 Agent 等）能搜索、查详情、 看排行，并把本子下载到本地。

底层用的是本仓库 src/jmcomic（pip install -e . 已装好）。 只新增 jmcomic_mcp/ 与几个入口文件，src/jmcomic 一行没动。

1. 安装

# Linux / macOS
./venv/bin/pip install -r requirements-mcp.txt   # 只装 mcp SDK
chmod +x run_mcp.sh

# Windows
venv\Scripts\pip install -r requirements-mcp.txt

mcp 依赖没有写进 pyproject.toml：上游声明 requires-python >= 3.7， 而 mcp SDK 要求 >= 3.10。混在一起会让上游失去 3.7 兼容性，所以单列一份 requirements-mcp.txt。当前 venv 是 3.13，满足要求。

Related MCP server: jmcomic-ai

2. 接到宿主

宿主配置就是一个 mcpServers 块，各家格式一致（Claude Desktop 的 claude_desktop_config.json、Cherry Studio 的 MCP 设置、Cursor 的 .cursor/mcp.json 都是这个结构）。把路径换成你 clone 下来的实际位置：

{
  "mcpServers": {
    "jmcomic": {
      "command": "/path/to/JMcomic-MCP/run_mcp.sh"
    }
  }
}

不用脚本也行，直接指解释器和入口：

{
  "mcpServers": {
    "jmcomic": {
      "command": "/path/to/JMcomic-MCP/venv/bin/python",
      "args": ["/path/to/JMcomic-MCP/jmcomic_mcp/server.py"]
    }
  }
}

Windows

不要配 run_mcp.sh。 那是 bash 脚本，Windows 宿主执行不了，表现是一直 显示"正在连接"然后断开。用仓库根目录的 run_mcp.bat，或者直接指解释器：

{
  "mcpServers": {
    "jmcomic": {
      "command": "D:/project/JMcomic-MCP/venv/Scripts/python.exe",
      "args": ["D:/project/JMcomic-MCP/jmcomic_mcp/server.py"]
    }
  }
}

用 run_mcp.bat 的话写 "command": "D:/project/JMcomic-MCP/run_mcp.bat" 即可， 它会自己检查 venv 和 mcp 依赖有没有装好，缺了就把原因打到 stderr。

WorkBuddy 会往 stdio 子进程环境里注入自己的代理变量。如果启动卡在 "Still connecting"，在 mcpServers 里补一段空代理配置： "env": {"http_proxy": "", "https_proxy": "", "NO_PROXY": "*"}。

3. 工具清单

典型用法是先查再下：search_album → get_album_detail → start_download。

4. 两件必须知道的行为

写入确认门

start_download 是唯一会写磁盘的写操作，实现成两步：

1. 第一次调用（confirmed=False）不会下载，只返回 status: confirmation_required 和一份计划（下哪些号、存到哪、多少并发）；

2. 模型把计划念给用户、拿到明确同意后，用完全相同的参数加 confirmed=True 再调一次，才真正开始。

这是工具自身的约束，不是靠模型自觉。

取消的语义

cancel_task 是不再开新的，收不回已经发出去的：

• 生效是立即的：信号一置位，之后不再发起任何新的图片请求，剩余章节直接跳过；

• 但还在传输中的那批收不回来，它们会跑完。数量约等于当时的并发数 （8 线程下一次大约 70 张）；

• 所以到 state 真正变成 cancelled 有一段收尾时间，并发越高、单张越慢就越长。 实测 63 章 / 8 线程那次：发出取消后约 40 秒才进终态，期间拦下了 1363 张没下的图。

• 判断信号有没有吃到，看 get_task 的 cancel_requested: true，别等 state。

比原 GUI 那套"只在两个本子之间检查标志位"的软停止实在得多。

进度字段怎么读

get_task 返回几种口径，别只看百分比：

为什么要分口径：长篇多章本子的图片总数要等每章开始才知道，用"已发现的图片数" 当分母会让百分比虚高（63 章那本头一分钟就显示 87%，其实才 3/63 章）。 所以多章本子按章节算；单章本子整章页数一次性到手，反而按图片算更准。

skipped_existing 用来解释「为什么 0 张也算成功」：重下已经下过的本子时， jmcomic 会跳过已存在的图、不调 after_image，所以 images 显示 0/50， 而 skipped_existing 是 50 —— 不是失败，是都跳过了。

结果字段：记账 vs 磁盘事实

三者不一致时以 verified 为准——verified.files 少于 images 的已完成数、 或者 empty_files > 0，都说明有文件没真正落盘。

清理半成品必须用 created_dirs，不要靠"哪个目录的修改时间比较新"去猜： 那个猜法已经实战翻车过一次——董卓 上+下 比 董卓 下 晚 14 秒，被误判成 新产物混进了删除清单，差点把上一次下的东西删掉。

created_dirs 只出现在 get_task 的返回里；list_tasks 是精简快照 （只给 created_dir_count），免得一次返回几十条路径。

失败原因（error_kind）

DNS 那一档是真去查一次再下结论的（socket.getaddrinfo），不是猜： 219 张全挂那次就是靠它定位到 CDN 域名被解析成 0.0.0.0。

image_cdn_unreachable 会被并发掩盖。 域名能解析、连接却失败，也可能是 自己并发开太高被站点限流了。看到这一档先确认是不是同时跑了多个任务、 image_threads 是不是被调到十几以上，再怀疑网络。

5. 下载目录与登录态

下载目录

默认 ~/Downloads/JMComic。三条硬规则：

1. 必须是绝对路径（支持 ~）。相对路径会被拒绝——MCP server 的 cwd 由宿主 决定，相对路径会让文件落到不可预期的位置。

2. 不能是磁盘根（D:\、/）、不能是用户主目录本身、不能落在系统目录 （C:\Windows、C:\Program Files、~/AppData、/etc、/usr 等）。 dest_dir 是模型可控参数，没有白名单的话一次 typo 就能把一本 200 页的本子 摊在 D:\ 根目录；要清理只能靠 created_dirs，前提是你先知道这事发生过。

3. 这个参数始终覆盖配置文件里的 dir_rule.base_dir。项目根目录里那堆本子就是 旧 GUI 漏了这一步造成的（当时下载目录只用来建空文件夹，从没写进 option， jmcomic 于是用了 os.getcwd()）。

并发闸门

两道闸，都是为了别把站点打到限流：

• image_threads 默认 8（不再用 jmcomic 的 30），上限 16，超了直接报错；

• 同时最多 2 个任务在真正下载，其余排队（state 保持 pending、 current 显示「排队中：等待并发下载槽位」），排队期间取消立即生效。

要更快就拆成多次调用让它们排队，别堆线程——堆线程只会让失败原因变成 image_cdn_unreachable，把自己引去换 DNS 开代理，查不出真原因。

登录态（收藏夹要用）

在任意位置写一个 option.yml，配 after_init 的 login 插件；构建 option 时会 自动登录并把 cookies 带上：

plugins:
  after_init:
    - plugin: login
      kwargs:
        username: 你的用户名
        password: 你的密码

然后把它的绝对路径传给工具的 config_file 参数（get_favorites、 search_album、start_download 等都支持）。客户端配置、代理、自定义域名 也都可以写在这个文件里。

client 按 (路径, mtime, 大小) 缓存，改了这个文件就会重新登录；即使不改， 缓存 30 分钟也会过期重建。所以 cookie 失效后不用重启宿主，重新调一次即可 （第一次会慢一点，它在重新登录）。

config_file 接受任意绝对路径，而 jmcomic 的 option.yml 支持插件机制 （能 import 并执行 Python）。这个参数是模型可控的，别让它指向来路不明的 配置文件——等于把代码执行面交出去。

6. 排错

• 日志全在 stderr。stdio 模式下 stdout 是 JSON-RPC 通道，jmcomic 自带日志 默认走 print()（jm_config.default_jm_logging），漏一行就会把宿主连接打断。 server.py 在导入第三方模块前就把 builtins.print 和 jmcomic 的日志执行器 都掰到了 stderr，并有专门的回归测试盯着这件事。

• 启动失败先手动跑一次看报错：./run_mcp.sh / run_mcp.bat（它不该输出任何 正常内容，只会有 stderr 日志）。

• 域名失效：jmcomic 会自己去拉最新域名；实在不行在 config_file 里写死 client.domain。

• 任务历史只存在内存里，server 重启后 get_task 找不到旧任务。重启不影响 磁盘上已下好的文件，重下会自动跳过（看 skipped_existing，不是失败）。

7. 自测

# 离线：61 个用例（参数解析、确认门、任务生命周期、取消、进度口径、
#      并发排队、缓存失效、dest_dir 校验、stdio 协议）
./venv/bin/python -m unittest discover -s jmcomic_mcp/tests -t .

# 联网：只读工具 + 下载路径端到端（dry run，不下载任何图片）
./venv/bin/python jmcomic_mcp/tests/live_check.py [album_id]

live_check.py 会替换掉"下载图片"这一步，只解析保存路径，用来确认 ①网络/域名通 ②保存路径真的落在 dest_dir 下。

上游来源与许可

本仓库的 src/jmcomic 是 hect0x7/JMComic-Crawler-Python 的副本（版本 2.6.9），未经修改，按 MIT 许可随附；原项目的 README 保留在 README.upstream.md。

jmcomic_mcp/、run_mcp.sh、run_mcp.bat、requirements-mcp.txt 及本 README 是在其之上的 MCP 封装层，同样遵循 MIT。上游版权归原作者所有。

本工具仅用于个人用途。它抓取的是第三方站点、内容版权归原权利人，请自行 确认所在地区的合法性；上游 README 也写了「为了减轻站点服务器压力，请不要 一次性爬取太多本子」——start_download 的 image_threads 参数就是给这个用的。