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 保存/恢复，几小时内免重复登录
🧰 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。