Zotero MCP

面向 Windows 与 WSL 的本地 Zotero MCP。读取走 Zotero Local API；需要修改 Zotero 时，先生成计划，再通过 Zotero Web API 执行并回读核验。

交给 Codex 配置

clone 仓库后，在仓库目录对 Codex 发送：

读取 AGENTS.md，按首次配置流程检查我的 Codex 与 Zotero 分别运行在 Windows 还是 WSL。账号注册、浏览器设置和密钥输入由我完成；你负责其余检测、配置与验证。

Codex 会先做只读检查。缺少 Zotero、MinerU 或 SciVerse 账号时，会给出官方入口并暂停；不会索要或显示密钥。

Related MCP server: zotero-grounded-mcp

安装

需要 Python 3.11 或更新版本。

git clone <repository-url> zotero-mcp
cd zotero-mcp
python -m venv .venv

Windows PowerShell 安装：

.\.venv\Scripts\Activate.ps1
python -m pip install .

WSL/Linux 安装：

source .venv/bin/activate
python -m pip install .

运行首次检查：

zotero-mcp setup plan --profile core

core 只要求 Zotero 读取链路。需要 Web API 写入、MinerU、QMD 与 SciVerse 时使用：

zotero-mcp setup plan --profile full

完整步骤见 docs/SETUP.md，账号边界见 docs/ACCOUNTS.md。

功能

• 检索、读取、匹配 Zotero 条目

• 按 key、唯一名称或完整路径解析 collection

• 读取批注、笔记、PDF 全文、页面与 Better BibTeX citation key

• 通过 plan/apply 两阶段工具导入论文、调整 collection、删除 PDF 附件

• 可选使用 MinerU 批量解析 PDF，并用 QMD 建立全文检索

• 按 toolset 控制暴露给 Agent 的工具

所有 apply 工具要求精确 key 和明确的 confirm=true。Web API 写入前会重新读取云端状态，写后回读核验。

Toolsets

• literature：检索、条目读取、collection 与论文导入

• review：批注、笔记、全文、MinerU 与页面工具

• maintenance：collection 调整与 PDF 附件删除

• all：全部公共工具

默认只启用 literature。生成 Codex 配置：

zotero-mcp setup print-codex-config --toolsets literature,review,maintenance

命令只输出配置块，不修改 Codex 配置文件，不包含密钥。

可用 MCP 工具：

• zotero_ping

• zotero_search

• zotero_match

• zotero_item

• zotero_children

• zotero_get_annotations

• zotero_get_notes

• zotero_get_citation_key

• zotero_collections

• zotero_resolve_collection

• zotero_item_collections

• zotero_collection_items

• zotero_web_api_status

• zotero_plan_paper_import

• zotero_apply_paper_import

• zotero_plan_collection_reconcile

• zotero_apply_collection_reconcile

• zotero_plan_pdf_attachment_delete

• zotero_apply_pdf_attachment_delete

• zotero_extract_text

• zotero_mineru_submit

• zotero_mineru_result

• zotero_render_pages

• zotero_find_figure_pages

可选集成

• Zotero Web API：只在写入时需要。

• MinerU：外部 PDF 解析服务，需要账号与 Token。

• QMD：本地检索工具，无账号要求。

• SciVerse：独立 MCP，用于文献检索，需要单独注册与登录。

• WebDAV：仅用于 Zotero 附件同步，不是 MCP 依赖。

完整文献工作流保持四段独立边界：SciVerse 检索候选，Zotero 查重并经 plan/apply 导入，MinerU 解析已确认的 PDF，QMD 更新索引并回读核验。任何外部上传或 Zotero 写入都需要单独批准。

配置位置

• Windows：%APPDATA%\zotero-mcp\config.toml

• WSL/Linux：~/.config/zotero-mcp/config.toml

可用 ZOTERO_MCP_CONFIG 指定配置文件，或用 ZOTERO_MCP_CONFIG_DIR 指定配置目录。环境变量与完整配置项见 docs/SETUP.md。

MinerU 批处理

单批预检与提交：

zotero-mineru plan <collection-key> --recursive
zotero-mineru submit-batch <collection-key> --recursive --max-pages 1000 --max-files 20
zotero-mineru collect <batch-id>
zotero-mineru verify <batch-id>

MinerU 与 QMD 的有界流水线：

zotero-mineru-qmd <collection-key> --recursive --page-budget 1000 --max-files 20

批次状态保存在 MinerU 输出目录的 .jobs 中。ledger 默认是同目录下的 mineru_todo.csv，也可通过配置项 mineru.ledger 或环境变量 ZOTERO_MINERU_LEDGER 指定。

测试

python -m unittest discover -v

常见故障见 docs/TROUBLESHOOTING.md。