cnki-mcp

把中国知网（CNKI）的文献检索 → 双排序去重 → PDF 下载 → 导入 Zotero（含 PDF 自动关联）→ 元数据核对更新封装成 MCP 工具，供 Claude 等 AI 助手一键调用。

An MCP server that lets an AI assistant search CNKI, download article PDFs, and import them into Zotero — with built-in deduplication, citation-based sorting, and PDF metadata reconciliation.

✨ 功能

• 多维排序检索：分别按「发表时间」和「引用量」取前 N 篇，合并去重后作为工作集

• 两级去重：(1) 两种排序结果间按标题去重；(2) 与 Zotero 已有文献对比，跳过已存在条目

• 引用量采集：检索结果中自动提取每篇论文的引用次数（CNKI td.quote）

• 下载 单篇或批量 PDF/CAJ 到本地

• 导入 Zotero：优先本地 connector（localhost:23119），PDF 直接上传并关联为子附件；Zotero 未运行时降级云 API（仅元数据）

• 元数据核对与更新：通过 PyMuPDF 提取 PDF 内嵌元数据（标题/作者/DOI），与 Zotero 条目比对生成差异表，用户确认后一键 PATCH 更新

• 登录态持久化：Cookie 保存/恢复，几小时内免重复登录

Related MCP server: Zotero MCP Agent

🧰 MCP 工具

cnki_batch 主要参数

📦 环境要求

• Python 3.10+（MCP SDK 要求）

• Playwright + 系统 Chrome（或内置 Chromium）

• 有效的 CNKI 机构访问权限（校园网/VPN/机构账号）

• 可选：Zotero 7+ 桌面端（用于 PDF 自动关联）

• 可选：Zotero API Key + Library ID（用于 Zotero 查重、元数据更新）

🚀 安装

方式 A：pip 安装（推荐，提供 cnki-mcp 命令）

pip install git+https://github.com/wuruiqi/cnki-mcp.git
python -m playwright install chromium   # 若无系统 Chrome

方式 B：克隆源码

git clone https://github.com/wuruiqi/cnki-mcp.git
cd cnki-mcp
pip install -r requirements.txt
python -m playwright install chromium
cp .env.example .env                     # 按需修改配置

注册到 MCP 客户端

pip 安装后（最简洁）：

{
  "mcpServers": {
    "cnki": { "type": "stdio", "command": "cnki-mcp" }
  }
}

克隆源码方式：

{
  "mcpServers": {
    "cnki": {
      "type": "stdio",
      "command": "python",
      "args": ["/abs/path/to/cnki-mcp/server.py"]
    }
  }
}

⚙️ 配置（.env）

所有项均可选。详见 .env.example。

提示：若需在导入后用 cnki_preview_metadata_updates 核对 PDF 元数据，请先将 DELETE_PDF_AFTER_IMPORT=false，或直接使用 cnki_batch 返回结果中自动生成的 metadata_preview。

📖 典型使用流程

1. cnki_login_status              → 检查登录态
2. cnki_open_login_page           → 机构登录（如需）
3. cnki_batch "螺旋推进 散粒体"    → 检索+排序+去重+下载+导入
   ↳ 返回 metadata_preview        → 查看 PDF 与 CNKI 元数据差异
4. cnki_apply_metadata_updates    → 确认后更新 Zotero 条目

⚠️ 说明与限制

• PDF 自动关联需 Zotero 桌面端在运行；未运行则降级为仅写元数据。

• cnki_apply_metadata_updates 需要 Zotero 云 API（在 .env 中配置 ZOTERO_API_KEY + ZOTERO_LIB_ID）。

• CNKI 每页约显示 20 条，top_n > 20 时实际返回数量受限（分页支持规划中）。

• 若系统配置了 HTTP 代理，访问 Zotero 本地端口已通过 httpx(trust_env=False) 处理。

• CNKI 验证码（CAPTCHA）：批量下载时如触发人机验证，下载将自动暂停并在控制台打印提示，请在保持打开的浏览器窗口中手动完成滑块验证后继续（等待上限 captcha_wait 秒，默认 120 秒）。浏览器须保持可见（headless=False，默认已满足）。

• IP 级人机验证风控：短时间内大量请求后，kns.cnki.net 可能把全部请求 302 到 /verify/home（滑块/点选验证），此时检索与下载都会失败——这与"是否登录"无关，连不带 JS 的 curl 也会被拦。处理方式：在浏览器里人工过一次验证（cnki_login_status 会返回 captcha: true 作为提示），或更换网络出口。

• 校外访问（CARSI / FSSO）登录同样被识别：cnki_login_status 采用多信号判定（会话 Cookie _shibsession_* / Ecp_session / SID_fsso / TDC_itoken，并结合页面文字），并回传 org（机构名）。注意此类登录后 www.cnki.net 顶部仍可能保留「机构登录」入口，属正常现象。

• 下载实现说明：CNKI 的下载按钮会弹出新标签页，且下载启动后页面会被站点关闭。因此本工具只用浏览器解析出签名下载地址，文件字节由 httpx 独立获取，避免浏览器退出导致下载中断。签名地址为一次性，请勿复用。

• 仅供个人学习研究用途，请遵守 CNKI 服务条款与所在机构的使用规定。

🛠 开发

pytest tests/test_unit.py -v    # 离线单元测试（19 个用例）

诊断脚本见 tests/（inspect_* 检查 DOM 选择器，probe_* 测试 Zotero 端点）。 实测要点、版本变更与 2026 改版适配记录见 docs/status.md。

License

MIT