54yyyu/zotero-mcp · 上手攻略

  • 仓库：54yyyu/zotero-mcp
  • 链接：https://github.com/54yyyu/zotero-mcp
  • 分类：academic-writing / agent
  • Stars：4221 | 周增：+147
  • 作者：Tom
  • 更新：2026-07-11

这是什么

zotero-mcp 是一个基于 Model Context Protocol（MCP） 的服务端工具，将你的 Zotero 文献管理库与 Claude、ChatGPT、Cursor 等主流 AI 助手连接起来，实现「用自然语言查阅、分析、管理文献库」的能力。

核心功能包括：按标题/作者/标签检索文献、语义相似性搜索（全库概念搜索，而非关键词匹配）、PDF 标注提取、BibTeX 导出、DOI 自动添加论文（带元数据与 PDF 自动获取）、引用统计分析（某篇论文被引用、支持还是反对）、论文撤回检测等。

最新版本支持语义搜索（ChromaDB 向量库）、PDF 大纲提取、EPUB 标注、语义研究智能体（找相关论文、图书馆覆盖率分析、标注综合等）。

最新版本：约 2026-07-03（Patch release），持续活跃维护。

解决什么问题

  1. 文献库太大，找不到需要的论文：Zotero 里存了几百上千篇文献，用自带的搜索只能按标题/作者精确匹配，无法做「找跟这篇论文研究思路相近的其他文章」这类语义搜索。

  2. 读论文效率低：PDF 读完想快速回顾核心观点，得手动翻笔记。zotero-mcp 可以提取 PDF 标注（高亮、批注）并按页码组织，方便 AI 帮你总结。

  3. 引用关系不透明：某篇论文被引用了多少次、支持/反对/提及分别多少，普通 Zotero 插件没有这个维度。zotero-mcp 通过 Scite API 提供这个信息，且无需 Scite 账号。

  4. 写论文时手动管理 BibTeX 繁琐：DOI 链接粘贴进来自动获取元数据 + PDFcascade（Unpaywall / arXiv / Semantic Scholar / PMC），省去手动填 metadata 的麻烦。

  5. 文献库无法被 AI 编程助手调用：Claude Code / Cursor 等 AI 工具无法直接读取本地 Zotero 数据库，zotero-mcp 通过 MCP 协议让 AI 安全地读写你的文献库。

快速安装

方式一：uv（推荐）

# 基础安装（搜索、读元数据、写操作，无 ML 依赖）
uv tool install zotero-mcp-server

# 完整安装（含语义搜索、PDF 提取、Scite 引用分析）
uv tool install "zotero-mcp-server[all]"

# 单独功能安装
uv tool install "zotero-mcp-server[semantic]"   # 语义搜索（ChromaDB）
uv tool install "zotero-mcp-server[pdf]"         # PDF 大纲提取 + EPUB 标注
uv tool install "zotero-mcp-server[scite]"       # 引用分析 + 撤回检测

方式二：pip

pip install zotero-mcp-server
pip install "zotero-mcp-server[all]"   # 完整版

方式三：pipx

pipx install zotero-mcp-server

安装后初始化配置

zotero-mcp setup

setup 命令会引导配置： - Zotero 本地库路径（或 Zotero Web API Key） - 语义搜索 embedding 模型选择（Default 免费本地模型 / OpenAI / Gemini / Ollama） - 数据库自动更新频率（手动 / 每次启动 / 每日 / 每 N 天）

macOS / Windows 无命令行经验用户：社区提供了 Zotero MCP Setup（图形化安装器 DMG + 一键脚本），无需接触终端。

核心用法

1. 初始化语义搜索数据库

语义搜索首次使用前需要构建向量索引：

# 构建语义搜索数据库（快速，元数据模式）
zotero-mcp update-db

# 强制重建索引（如换了 embedding 模型）
zotero-mcp update-db --force-rebuild

# 带上全文提取（更慢但更全面）
zotero-mcp update-db --fulltext

# 指定自定义 Zotero 数据库路径
zotero-mcp update-db --fulltext --db-path "/Your_custom_path/zotero.sqlite"

注意：如果选用 OpenAI Embedding，setup 过程会询问是否用 OpenAI Batch API（批量提交，便宜但异步，需等待完成再 import）。

2. 在 AI 助手中使用（Claude Desktop 示例）

在 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或对应配置文件（Windows）中添加：

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--from", "zotero-mcp-server", "zotero-mcp"]
    }
  }
}

重启 Claude Desktop，即可在对话中直接使用 zotero MCP 工具（搜索、读文献、分析引用等）。

3. 在终端直接使用（无需 AI 助手）

# 搜索文献（title/author/content）
zotero-mcp search "machine learning applications in neuroscience"
zotero-mcp s "transformer attention mechanism"   # 短别名

# 获取文献 metadata（Markdown 格式）
zotero-mcp get "DOI_or_CitationKey"

# 导出 BibTeX
zotero-mcp bibtex "DOI_or_CitationKey"

# 读 PDF 标注
zotero-mcp annotations "DOI_or_CitationKey"

# 管理收藏夹
zotero-mcp collections list
zotero-mcp coll create "新收藏夹"
zotero-mcp coll add "paper_key" "收藏夹名"

# 查找相似论文（语义搜索）
zotero-mcp search "papers similar to this concept: [paste abstract]"

# 数据库状态
zotero-mcp db-status

# 检查更新
zotero-mcp update --check-only
zotero-mcp update   # 更新到最新版本（保留配置）

4. 语义搜索的 Embedding 模型选择

模型 费用 说明
Default（all-MiniLM-L6-v2） 免费、本地运行 轻量，默认推荐，大多数场景够用
OpenAI text-embedding-3-small/large OpenAI API 计费 质量更高，需要 API Key
Gemini gemini-embedding-001 Gemini API 计费 同上
Ollama（本地自托管） 免费 支持 qwen3-embedding、nomic-embed-text、bge-m3 等

Ollama 本地部署示例：

# 启动 Ollama 服务
ollama serve

# 拉取轻量 embedding 模型（推荐）
ollama pull nomic-embed-text

# 或拉取中量级多语言模型（中文检索质量更好）
ollama pull bge-m3

# 在 zotero-mcp setup 中选择 Ollama，输入模型名即可

5. 引用分析（Scite）

无需 Scite 账号，使用公开 API 端点：

# 某篇论文的支持/反对/提及引用统计
# 在 AI 助手中直接问：
# "这篇论文在 Zotero 库里被引用情况如何？支持、反对、提及各多少？"

6. 论文撤回检测

# 在 AI 助手中问：
# "我的 Zotero 库里有没有被撤稿的论文？扫描一下。"

典型使用场景

场景 对话示例
找相关论文 「找 5 篇跟 'diffusion model in medical imaging' 语义最相似的论文」
批量找某领域文献 「我库里有几篇关于 LLM 的论文，它们之间有什么引用关系？」
论文速读 「帮我读一下这篇 PDF 的标注，列出每条高亮对应的页码和内容」
引用统计 「300474 这篇论文的支持引用和反对引用各是多少？」
新论文入库 「帮我用 DOI 10.xxxx 添加这篇论文，并自动找开源 PDF」
整理收藏夹 「把库里所有标注了『重要』标签的论文导出一个 BibTeX 文件」
撤回检测 「我的库里有撤回论文吗？」
写作时插入引用 「在当前文档里插入 Zotero 中 key 为 XXX 的论文引用，格式用 APA」

坑与注意

  1. ChromaDB ≥ 1.x 兼容性（2026-07-03 patch 已修复）：旧版 zotero-mcp 在 ChromaDB ≥ 1.x 环境下，zotero_get_search_database_status 会错误报告「0 documents / not initialized」。更新到最新版即可解决。

  2. OpenAI Batch API 是异步的：大库（数千篇论文）用 Batch API 建索引需要等待后台任务完成（可能数小时），期间需定期运行 zotero-mcp openai-batch-status 轮询，完成后手动 import。中小库直接用同步模式更快。

  3. Ollama embedding 路线升级（2026-07-03 patch 已修复）：旧版对每篇文档单独发一次 /api/embeddings 请求（数千篇 = 数千次请求，30 秒/篇）；新版改为批量 /api/embed 一次提交，大幅提速。

  4. 语义搜索 reranker 性能问题（2026-07-03 patch 已修复）：旧版开启 reranker 时每次搜索要 ~30 秒重新加载 cross-encoder；新版已缓存进程级，第二次搜索即在 1 秒内。

  5. Local 模式 vs Web API 模式： - Local 模式：纯本地 Zotero.sqlite，无需网络，零 API Key，所有读写操作走本地文件 - Web API 模式：读写 Zotero 云端同步库，适合多设备用户 - Hybrid 模式：本地读 + Web API 写，兼顾离线能力与多设备同步

  6. PDF 全文索引体积：对大库（>5000 篇）做 fulltext 索引可能占用数 GB 磁盘空间。语义索引（只用 metadata，不索引全文）轻量得多。

  7. Zotero 版本要求：建议 Zotero 6.0+；部分功能（如 PDF 标注提取）依赖 Zotero PDF 解析功能。

  8. macOS Apple Silicon（M1/M2/M3）注意：某些 ML 依赖（sentence-transformers）安装时可能需要 Rosetta 2 或特定 wheel，建议通过 uv 安装以获得更好的环境隔离。

与同类对比

工具 协议 语义搜索 PDF 标注 引用分析 撤回检测 本地优先
zotero-mcp（本文） MCP ✅ ChromaDB ✅ ✅ Scite ✅ ✅
Zotero 内置搜索 — ❌ 仅关键词 ❌ ❌ ❌ ✅
Zotero AI GPT Plugin 非标准 ❌ ✅ ❌ ❌ ❌ 需云
scite-zotero-plugin Zotero 插件 ❌ ❌ ✅ ✅ ✅
Semantic Scholar API Web API ✅ ❌ ✅ ❌ ❌
ResearchRabbit Web 应用 ✅ 图谱 ❌ ✅ ❌ ❌

zotero-mcp 的核心优势在于：本地优先 + MCP 协议 + 多 AI 助手兼容。不绑特定云服务，不依赖 Zotero 官方 AI 功能，通过开放的 MCP 协议让任何 MCP-compatible AI 助手都能用。

一句话结论

让 Zotero 文献库真正成为 AI 编程助手的研究记忆——语义搜索、PDF 标注提取、引用分析、DOI 自动入库、撤回检测，全部本地优先、MCP 协议驱动，适合重度学术写作与文献综述场景。

持续维护中，最新版本请查看 GitHub Releases。 社区图形化安装：ehawkin/zotero-mcp-setup。