cookjohn/zotero-mcp · 上手攻略
- 仓库：cookjohn/zotero-mcp
- 链接：https://github.com/cookjohn/zotero-mcp
- 分类：学术工具 · MCP 集成
- 作者：Tom
- 更新：2026-08-12
是什么
Zotero MCP 是一个 Zotero 插件，通过 MCP（Model Context Protocol）协议将你的本地 Zotero 文献库与 AI 助手（Claude Desktop、Cursor IDE、Gemini CLI 等）连接起来的桥梁。它让 AI 能够直接搜索、查询、引用你的文献库，大幅提升文献综述和学术写作效率。
当前版本：1.5.0（据 GitHub badges），采用统一架构——MCP 服务器直接集成在 Zotero 插件内部，使用 Streamable HTTP 协议，无需单独启动服务器进程。
解决什么问题
学术写作中最大的低效来源之一是文献与 AI 写作工具之间的割裂：在 Zotero 管理文献，用 AI 助手写论文，两者之间需要手动复制粘贴、切换窗口、格式不统一。
Zotero MCP 把这个流程自动化：AI 助手可以直接查询你的 Zotero 库，提取 PDF 全文、分析批注、按主题检索相关文献，然后直接引用——整个过程不需要你介入。
快速安装
前置要求
- Zotero 7.0 或更高版本
- Node.js 18+（仅开发模式需要）
- AI 客户端支持 Streamable HTTP MCP（Claude Desktop、Cursor IDE、Cherry Studio 等）
安装步骤
方式一：直接安装插件（推荐普通用户）
- 前往 Releases 页面 下载最新版
zotero-mcp-plugin-x.x.x.xpi - Zotero →
工具→附加组件→ 齿轮图标 →Install Add-on From File...→ 选择下载的.xpi文件 - 重启 Zotero
方式二：开发者模式
git clone https://github.com/cookjohn/zotero-mcp.git
cd zotero-mcp/zotero-mcp-plugin
npm install
npm run build
# 开发模式（自动重载）
npm run start
配置 AI 客户端
在 Zotero 中打开 首选项 → Zotero MCP Plugin 标签页：
- 勾选 Enable Server（启用集成 MCP 服务器）
- 端口：默认
23120（可自定义） - 点击 生成客户端配置 → 复制配置代码
Claude Desktop 配置示例（claude_desktop_config.json）：
{
"mcpServers": {
"zotero": {
"transport": "streamable_http",
"url": "http://127.0.0.1:23120/mcp"
}
}
}
配置文件路径：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
核心用法
MCP 工具分类（20+ 工具，5 大类）
搜索类
| 工具 | 功能 |
|---|---|
search_library |
多维度布尔搜索（标题/作者/年份/标签/全文），带相关性评分 |
semantic_search |
基于向量嵌入的语义搜索（OpenAI / Ollama） |
get_item |
获取单条文献的完整元数据 |
get_items_by_identifiers |
通过 DOI、ISBN、arXiv ID 等精确查找文献 |
内容提取类
| 工具 | 功能 |
|---|---|
get_item_content |
提取 PDF 全文/笔记/摘要，支持四种粒度（minimal/preview/standard/complete） |
get_attachment |
获取附件（PDF）内容 |
get_annotation |
按颜色/标签/关键词检索 PDF 批注 |
集合管理类
| 工具 | 功能 |
|---|---|
get_collections |
获取收藏夹层级结构 |
get_collection_items |
获取某收藏夹下所有文献 |
create_collection |
创建新收藏夹 |
写入操作类
| 工具 | 功能 |
|---|---|
create_note |
在文献下创建笔记 |
update_item |
更新文献元数据 |
add_tags |
给文献添加标签 |
create_item |
新建文献条目并关联 PDF |
全文数据库类
| 工具 | 功能 |
|---|---|
fulltext_search |
搜索 PDF 全文缓存 |
get_fulltext_stats |
全文数据库统计 |
日常使用示例
"帮我查找 Zotero 库里所有关于 transformer 的期刊文章"
"获取 2024 年由 Hinton 发表的关于大语言模型的论文"
"查找 DOI 为 10.1038/nature14539 的文献"
"总结我库中关于强化学习的 PDF 全文"
典型适用场景
- 文献综述写作：AI 直接读取库中 PDF 全文，写文献综述时自动引用
- 论文写作：让 AI 根据你的文献库内容生成初稿或润色
- 跨语言文献发现：语义搜索发现不同语言的相关研究
- 组会汇报准备：快速检索某主题下的所有批注和高亮
- 知识管理：用 AI 组织、归类、重构文献笔记
坑与注意
⚠️ Zotero 必须保持运行：MCP 服务器运行在 Zotero 进程内，关闭 Zotero 后 AI 客户端连接断开。
⚠️ 端口冲突：如果 23120 被占用，更换端口后需同步更新 AI 客户端配置。同时在 zotero-mcp-plugin/ 目录下创建 .env 文件：ZOTERO_API_PORT=新端口号。
⚠️ 语义搜索需要 API Key：语义搜索功能支持 OpenAI 和 Ollama，需要配置相应的 API Key 或本地 Ollama 服务。embedding provider 预设支持：OpenAI、Google Gemini、阿里云百炼、智谱 AI、OpenRouter、硅基流动、Voyage AI、Ollama。
⚠️ 全文索引需要手动构建：语义搜索和全文数据库首次使用需要为 PDF 构建索引，库较大的情况下首次索引耗时较长。Zotero 库视图中有索引状态列，可通过右键菜单管理索引。
⚠️ Streamable HTTP 是新协议：部分老版本 AI 客户端可能不支持，需要更新到最新版。
⚠️ 安全边界：插件仅本地运行，所有数据不离开本机，但 MCP 协议本身会暴露 Zotero 库内容给 AI 客户端，注意不要向 AI 发送敏感未发表研究。
⚠️ Zotero 7 专用：不兼容 Zotero 6，请确认版本后再安装。
与同类对比
| 特性 | Zotero MCP | muisedestiny/zotero-gpt | muisedestiny/zotero-reference |
|---|---|---|---|
| 协议 | MCP（标准化） | 独立服务器 | 独立服务器 |
| 安装 | Zotero 插件 | 需跑 Node 服务器 | 需跑 Node 服务器 |
| 搜索能力 | 布尔 + 语义 + 全文 | GPT 语义 | GPT 语义 |
| 写入操作 | ✅ 完整 | 有限 | 有限 |
| 架构 | 插件内置 MCP | 外部 MCP 服务器 | 外部 MCP 服务器 |
| 维护状态 | 活跃（2026） | 较旧 | 较旧 |
| AI 客户端 | 广泛（MCP 通用） | 特定 | 特定 |
Zotero MCP 的架构优势在于统一性：插件即 MCP 服务器，不需要维护单独的 Node 进程，对普通用户更友好。
一句话推荐结论
如果你是 Zotero 7 + Claude Desktop / Cursor 用户，想让 AI 直接读写你的文献库，Zotero MCP 是目前最低门槛的方案——装一个插件、配两行 JSON，就能实现文献到 AI 的无缝直连；不需要维护独立服务器，也不需要额外部署。