Zotero MCP Server

什么是 Zotero MCP Server？

Zotero MCP Server 是一个社区开发的 zotero mcp 连接器，让 Claude 和其他 MCP 客户端通过 Zotero Web API 读取你的 Zotero 文献库：列出文献集、打开条目、搜索参考文献，以及查看最近添加的论文。

它是 kaliaboi 开发的开源 Node.js 项目（MIT 许可证），在 npm 上以 mcp-zotero 发布，并非 Zotero 官方团队出品。它使用 API 密钥访问你的 Zotero 云端文献库（zotero.org），因此文献库必须已同步到线上；它不会直接读取 Zotero 桌面端的本地数据库。

如何使用 Zotero MCP Server？

你需要 Node.js（用于 npx/npm）、一个已同步文献库的 Zotero 账号，以及两个值：Zotero API 密钥和你的数字用户 ID。

1. 在 https://www.zotero.org/settings/keys 创建 API 密钥。
2. 用该密钥查询你的用户 ID：

curl -H "Zotero-API-Key: YOUR_API_KEY" https://api.zotero.org/keys/current

返回的 JSON 中包含 userID 字段，这个数字就是你的 ZOTERO_USER_ID。

3. 设置环境变量并验证是否可用：

export ZOTERO_API_KEY="your-api-key"
export ZOTERO_USER_ID="user-id-from-curl"

curl -H "Zotero-API-Key: $ZOTERO_API_KEY" \
     "https://api.zotero.org/users/$ZOTERO_USER_ID/collections"

如果能看到你的文献集列表，说明凭据有效。

4. 安装并运行服务器：

# Install globally
npm install -g mcp-zotero
mcp-zotero

# Or run directly with npx
npx mcp-zotero

只要缺少其中任一变量，服务器就会报错 "Missing ZOTERO_API_KEY or ZOTERO_USER_ID environment variables" 并退出，因此下面每个客户端配置都会在 env 中传入这两个值。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（来自 README；请用引号包住你的值）：

{
  "mcpServers": {
    "zotero": {
      "command": "mcp-zotero",
      "env": {
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "ZOTERO_USER_ID": "YOUR_USER_ID"
      }
    }
  }
}

这种写法需要先全局安装。若未全局安装，可以像本页展示的配置那样使用 "command": "npx" 和 "args": ["mcp-zotero"]。

Claude Code

claude mcp add zotero \
  -e ZOTERO_API_KEY=YOUR_API_KEY \
  -e ZOTERO_USER_ID=YOUR_USER_ID \
  -- npx -y mcp-zotero

Cursor

将同样的 mcpServers 配置块添加到 ~/.cursor/mcp.json（或项目内的 .cursor/mcp.json），以 npx 和 mcp-zotero 作为 command 和 args，并在 env 中填入这两个变量。

Zotero MCP Server 的主要功能

• 列出你个人 Zotero 文献库中的所有文献集及其 key。
• 返回某个文献集中的条目，包含标题、作者、日期、条目类型、摘要、标签、DOI、URL 和出版物名称。
• 按 key 获取单个条目的完整信息，包括它所属的文献集。
• 根据纯文本查询，通过 Zotero Web API 搜索整个文献库。
• 按添加时间显示最近添加的论文（默认 10 篇，上限 100 篇）。
• 代码量小：单个 TypeScript 文件，基于 zotero-api-client 和官方 MCP SDK，使用 stdio 传输。
• 以 mcp-zotero 发布在 npm 上；仓库中还提供 Dockerfile 和 Smithery 配置。

Zotero MCP Server 工具

该服务器提供五个只读工具，分为两组：

• 浏览：get_collections 列出你的文献集及其 key；get_collection_items 接收文献集 key 并返回其中的条目；get_item_details 接收条目 key 并返回该论文的完整元数据。
• 查找：search_library 接收 query 参数并搜索整个文献库；get_recent 返回最新添加的条目，可选 limit 参数。

这些工具都不会创建、编辑或删除条目。Claude 可以阅读和总结你的参考文献，但无法通过此服务器修改你的文献库。

Zotero MCP Server 的使用场景

• 文献综述准备：“列出我 'Thesis – Chapter 2' 文献集中的论文，并按研究方法分组。”
• 找回记不清的来源：“在我的 Zotero 文献库中搜索关于 transformer 可解释性的论文，并给出它们的 DOI。”
• 快速获取引用信息：“获取这个条目的详情，并把作者、年份和期刊整理成参考文献格式。”
• 跟进最近的阅读：“显示我最近添加的 20 篇论文，并总结它们的摘要。”
• 标签与主题概览：“在我的 'Climate policy' 文献集中，哪些标签出现得最多？”

Zotero MCP Server 与替代方案对比

主要替代方案是 54yyyu 的 zotero-mcp，这是另一个独立的社区项目，开发活跃得多，使用 Python 编写（pip install zotero-mcp-server）。它既可以通过 Zotero 7 的本地 API（ZOTERO_LOCAL=true）连接，也可以使用 Web API；其 README 还列出了语义搜索、PDF 与批注支持，以及可自动配置 Claude Desktop 的 zotero-mcp setup 等扩展功能。

如果你想要一个小巧、只读、只需 API 密钥即可浏览和搜索的 Node.js 服务器，选择 kaliaboi 的 mcp-zotero server；如果你需要无需云端密钥的本地文献库访问、全文或语义搜索，或批注功能，选择 54yyyu 的 zotero-mcp server。两者都不是 Zotero 官方产品。

Zotero MCP Server 常见问题排查

• 服务器无法启动 / 缺少变量：运行 echo $ZOTERO_API_KEY 和 echo $ZOTERO_USER_ID 检查，并确认两个变量都写在客户端的 env 配置块中，而不只是设置在你的 shell 里。
• 找不到命令：运行 npm list -g mcp-zotero 检查全局安装。如果安装损坏，先运行 npm uninstall -g mcp-zotero 再运行 npm install -g mcp-zotero，或者把配置改为使用 npx。
• 结果为空：运行上文的 curl .../collections 检查。用户 ID 错误（填成了用户名）、密钥过期，或文献库未同步到 zotero.org，都会导致没有返回结果。
• 只返回部分条目或文献集：一个未关闭的 issue（#14）反馈，文献集和文献集条目只返回 Zotero API 结果的第一页（约 25 条）。非常大的文献库可能显示不完整。
• 每次调用都报 "fetch failed"：一个未关闭的 issue（#18）反馈，在只能通过 HTTP(S) 代理访问互联网的网络中，服务器会调用失败。