Zotero MCP

让 AI agent 直接维护你的 Zotero 库:搜索、改元数据、批量打 CCF 级别标签、导入 PDF,不需要 Zotero 开着。

MCP server 直连 zotero.sqlite,把 Zotero 当成一个带 PDF 阅读器的数据库。agent 负责整理和标注,你负责阅读和思考。

能做什么

"把库里所有 OSDI 的论文标成 CCF-A"
"这篇的 DOI 写错了,改成 10.xxx/yyy"
"帮我看看 IEEE TPDS 是几类"
"这个 PDF 导进库里,顺带补上元数据"

两种用法,按需选

形态	适合	Zotero 要开吗
MCP server	agent 自动化维护库	不用
插件	在 Zotero 界面里看分级、右键识别、阅读时记笔记	要用

两者共用同一份 CCF 目录,结果一致。

快速开始: MCP server

cd mcp-server
npm install

配置到 Claude Desktop(claude_desktop_config.json)或 Cursor(.cursor/mcp.json):

{
  "mcpServers": {
    "zotero": {
      "command": "node",
      "args": [
        "/path/to/zotero-mcp/mcp-server/server.mjs",
        "--db", "/path/to/Zotero/zotero.sqlite"
      ]
    }
  }
}

--db 可省略,会自动找 ZOTERO_DB、ZOTERO_DATA_DIR、~/Zotero、%APPDATA%/Zotero。

工具

工具	用途
zotero_search	按标题/作者/venue/DOI/标签搜索
zotero_get	读单条全部字段、作者、标签、附件路径
zotero_stats	库统计
zotero_tags / zotero_collections	标签与集合清单
zotero_update_fields	改元数据(改完 Zotero 下次打开即生效)
zotero_set_creators	替换作者列表
ccf_lookup	查一个期刊/会议属于哪级,纯查询
ccf_detect	批量识别并写成标签,幂等
zotero_add_tags / zotero_remove_tags	增删标签
zotero_pdf_import	导入本地 PDF

分级:两套体系

体系	标签	覆盖范围	来源
CCF	CCF-A / CCF-B / CCF-C	国际会议与期刊(英文)	CCF 第七版推荐目录,681 条
T	T-T1 / T-T2 / T-T3	期刊,中英文都有	计算领域高质量科技期刊分级目录(2025),65 条

两套是独立的:CCF 目录只收国际英文刊会,所以中文期刊不会有 CCF 等级;T 目录只评期刊,所以会议不会有 T 等级。一本英文期刊可以同时有两个。

数据都解析自 CCF 公开发布的 PDF,不是手工抄录。版本、字段结构、匹配策略和更新方法见 docs/catalog-sources.md。

查级:

{ "venue": "IEEE Transactions on Parallel and Distributed Systems" }
→ { "ccf": "A", "t": null }

{ "venue": "计算机研究与发展" }
→ { "ccf": null, "t": "T1" }

批量打标签后,等级会以彩色标签出现在文献列表里,侧栏点一下就能筛出所有 A 类。

标签必须配色才会显示在列表中 —— Zotero 只渲染有颜色或含 emoji 的标签。工具已自动处理。

插件

plugin/dist/pmlink-4.0.0.xpi

安装:Zotero → 工具 → 插件 → 右上齿轮 → Install Add-on From File。

提供:

• CCF 列:文献列表里显示分级,按等级排序
• 详情行:CCF / T / 相关性 / 标签
• 右键菜单:批量识别 CCF、清除分级、导入 PDF、添加阅读笔记
• 阅读器集成:选中文本 → “存为笔记”

从 Paper Manager 迁移

如果你之前用 Paper Manager,scripts/ 提供了完整的迁移链路:

# 1. 从 pm 库导出迁移清单(只读)
PAPER_MANAGER_DB="/path/to/paper-manager-data" \
  node scripts/build-manifest.mjs

# 2. 生成 Zotero 导入数据
PM_PDF_DIR="/path/to/paper-manager-data/pdfs" \
  node scripts/prepare-import.mjs

# 3. 在 Zotero 里运行 scripts/zotero-import.js
#    (工具 → 开发者 → Run JavaScript,先改 CONFIG.dataFile / resultFile)

迁移脚本是幂等的,中断后重跑会跳过已导入的条目,只补挂缺失的 PDF。

技术要点

写这个仓库时踩过、值得记下来的:

自定义字段只能用 Extra。 Zotero 的字段 schema 是编译期固定的,没有面向插件的注册 API。DB 里的 customFields 表受外键约束,只能挂到自定义 itemType 上,挂不到内置的 journalArticle/book。所以分级只能走标签或 Extra。

getExtraField 读不到自定义 key。 Zotero 的 extra 解析器只认内置字段名和 CSL 变量,行正则 /^([a-z][a-z -_]+):/ 连 CJK 键都拒绝。要读 CCF: 这类自定义键,必须自己解析 Extra 原文。

标注的坐标只能由 reader 产生。 是 PDF 用户空间坐标、y 轴从页面底部起算。从”页码 + 文本”反推不可靠,所以插件只提供”从当前选区建高亮”。

直接写库的约束。 WAL 模式 + 外键开启,代码里强制:BEGIN IMMEDIATE + busy_timeout;写完更新 items.synced / dateModified / libraries.version;itemDataValues 复用已有行;标签走 tags + itemTags 两表。

更多插件开发踩坑见 docs/plugin-development-notes.md。

开发

cd mcp-server
npm install
npm test              # ZOTERO_DB=<路径> 后才真正跑;没设置会跳过

npm test 走真实 MCP 协议(stdio),覆盖搜索、统计、标签分布、两级查询、批量识别幂等。没有 Zotero 库时打印 SKIP 并返回 0,方便 CI。

许可

MIT。CCF 目录数据来自中国计算机学会公开目录,仅供个人学术检索使用。