Zotero MCP 安装配置与 AI 客户端连接指南

更新于 2026-10-26 · jetstream.mom

简答：Zotero MCP 不是单一插件，而是让 AI 客户端通过 MCP Server 访问 Zotero 的连接方案。建议先选实现，再用本地只读模式完成搜索验证；需要远程访问或写入时，再配置 Web API 或本地写入授权。

定义：Zotero MCP 是遵循 Model Context Protocol 的服务端程序，用于把 Zotero 条目、附件、全文或写入能力暴露给支持 MCP 的 AI 客户端。

先给结论：Zotero MCP 应该怎么选

如果你的目标只是让 AI 搜索本机 Zotero 条目，先选支持本地 stdio 的实现，并使用 Local read-only。它不需要 Web API Key，排查范围也较小。需要跨设备访问时再考虑 Web API；需要写入条目、标签、笔记或附件时，必须单独核对该实现的写入方式。

实现或模式	适合场景	前置条件	需要注意
54yyyu/zotero-mcp	希望用 Python/uvx 快速接入，并按 Local、Web API、Hybrid 切换	项目文档列出 Python 3.10+、Zotero 7+和 MCP 客户端	命令、环境变量和本地写入授权均是该项目的封装，不代表所有 Zotero MCP 都支持
richardjlyon/zotero-mcp	偏好 Rust、本地优先，或需要 stdio、HTTP/SSE、OAuth 方案	项目 README 列出 Rust 1.75+、运行中的 Zotero 和本地通信设置	其写入路径、PDF 提取依赖和配置文件与 Python 实现不同
Local read-only	本机搜索条目和读取本地资源	Zotero 正在运行，并允许其他应用通信	不等于自动拥有 PDF OCR、语义搜索或写入能力
Web API	远程访问同步库	zotero.org API Key、Library ID和库类型	写入权限应按最小范围设置，密钥不要放进公开配置
Hybrid	本地读取、Web API 写入	本地连接加 Web API 凭据	这是部分实现提供的模式，配置前要看对应项目文档

本文选择 54yyyu/zotero-mcp 作为主流程，是因为其公开文档集中说明了 Local、Web API、Hybrid、客户端设置和全文提取；richardjlyon/zotero-mcp 作为对照，适合偏好 Rust、本地优先和 HTTP/OAuth 的用户。两者并非同一个项目，不能混用安装命令、变量名或配置文件。

参考：54yyyu/zotero-mcp 项目主页、richardjlyon/zotero-mcp 项目主页。

安装前检查：版本、权限与连接方式

确认 Zotero 桌面端正在运行。在设置的 Advanced 或高级选项中，开启“Allow other applications on this computer to communicate with Zotero”。54yyyu 项目将 Zotero 7+列为本地 API 与全文访问的前置条件；Zotero 官方文档则单独说明了 Zotero 10+本地写入授权，不应把两者合并成“所有写入都支持”。
确认运行环境。54yyyu 项目文档列出 Python 3.10+，并提供 uv、pip、pipx 安装方式。命令只适用于该项目：uv tool install zotero-mcp-server pip install zotero-mcp-server pipx install zotero-mcp-server
先决定读还是写。只读本地连接可设置 ZOTERO_LOCAL=true。Web API 访问则需要 ZOTERO_API_KEY、ZOTERO_LIBRARY_ID，群组库还要设置 ZOTERO_LIBRARY_TYPE=group。
核对密钥权限。Zotero 官方文档明确要求 Web API 写请求使用具有写入权限的 API Key；本地 API 的写入 Key 则由 Zotero 运行时授权，两者不是同一种密钥。可查看Zotero Web API 写入文档和Zotero Local API 文档。

最小本地只读配置可以先写成：

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

如果客户端找不到 zotero-mcp，不要立即改成另一个项目的命令。先执行该项目文档提供的 zotero-mcp setup-info，或在终端使用 which zotero-mcp、Windows 下使用 where zotero-mcp，把绝对路径填入客户端配置。

PDF 全文、OCR、注释和页面引用的前置条件

“能连接 Zotero”不等于“能可靠阅读所有 PDF”。至少要区分以下四层：

附件读取：服务端先要能看到 Zotero 条目及其子附件；附件文件路径、权限和 Zotero 是否正在运行都会影响结果。
PDF 文本层：有文本层的 PDF 更容易被提取。54yyyu 项目文档说明其 PDF 提取对普通正文较可靠，对数学公式和表格可能不可靠，并支持按页读取或返回页面图像。
OCR：当前检索到的上述项目文档没有证明“内置 OCR 对扫描 PDF 自动生效”。扫描件如果没有文本层，应把 OCR 视为额外前置步骤，不要把空结果直接判断为 MCP 连接失败。
注释和页面级引用：richardjlyon 项目 README 明确列出 PDF 文本、注释、页面锚点等能力；54yyyu 项目则公开了全文提取、页面读取和附件优先级。具体工具名称和返回格式必须以所选实现实际暴露的工具为准。
语义搜索：54yyyu 项目把全文提取和语义数据库更新分开，使用 zotero-mcp update-db --fulltext 等项目命令时，才涉及额外索引流程。它不是 Zotero Local API 自带的能力。

因此，首次验证不要直接要求 AI“总结整个库”。先测试一个条目：搜索标题、读取元数据、列出附件、读取一页 PDF；每一步都成功后，再测试全文或注释。

参考：54yyyu 配置文档、richardjlyon 项目说明。

Claude Desktop：导入、开启、验证三步

导入：打开 Claude Desktop 的 MCP 配置文件。54yyyu 文档列出的常见位置是 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 的 %APPDATA%\Claude\claude_desktop_config.json，然后加入上一节的 JSON 配置。
开启：完全退出并重新启动 Claude Desktop，确认 Zotero 桌面端已运行且本地通信已开启。若使用 Web API，把 API Key 和 Library ID 放进同一服务的 env，不要把它们混到另一个 MCP 实现的配置格式中。
验证：在 Claude 的工具或连接界面检查是否出现 Zotero 工具，然后依次询问“搜索一个已知标题”“读取该条目的元数据”“列出附件”。日志入口：若界面没有统一日志路径，优先回到配置文件、客户端连接状态和启动终端检查；项目文档没有提供适用于所有系统的统一日志目录。

如果出现“找不到命令”，用绝对路径替换 command；如果工具出现但搜索为空，先确认 Zotero 正在运行、库没有切错，再测试 Web API 的 Library ID。

参考：54yyyu 客户端接入文档。

Claude Code：导入、开启、验证三步

导入：Claude Code 使用 ~/.claude.json 或官方 MCP 管理命令配置服务。可以先执行 claude mcp 查看命令帮助，再按项目文档加入 Zotero 服务。
开启：启动 Claude Code 后，用 /mcp 查看连接状态。Anthropic 官方文档把 MCP 作为 Claude Code 的扩展连接方式，并提醒第三方服务的安全性需要自行核验。
验证：依次测试条目搜索、附件列表和一页文本读取。日志入口使用 claude --verbose 获取更详细的运行输出；不要用跳过权限的方式代替故障定位。

Claude Code 也可能通过项目技能或 CLI 访问 Zotero，但这与 MCP Server 是两条路径。项目文档列出 zotero-mcp install-skill，该命令只属于 54yyyu 项目，不能当作通用 Zotero 命令。

参考：Anthropic MCP 文档、Claude Code CLI 文档。

ChatGPT：先确认远程 MCP 条件

导入：ChatGPT 的自定义 MCP 应用需要在网页端开发者模式或工作区应用设置中创建，并填写远程 MCP 服务端点。OpenAI 官方文档说明，ChatGPT 不能直接连接只在本机运行的 MCP Server。
开启：管理员或符合条件的工作区需要启用 Developer mode，并在创建应用时扫描工具、选择认证方式。把本机服务暴露到远程网络前，要先评估数据和写入风险。
验证：创建后打开新对话，从工具菜单选择应用，先执行只读搜索和读取测试。日志入口主要是应用创建页面的工具扫描结果、对话中的工具调用和服务端运行日志；若工具扫描失败，先检查远程端点、传输方式和认证。

ChatGPT 这一条与 Claude Desktop、Cursor 的关键差异是：前两者可直接使用本地 stdio 配置，而 OpenAI 官方资料要求 ChatGPT 连接远程 MCP 服务；可用计划、开发者模式和写入能力还可能随工作区策略变化。不要把某个开源项目 README 中的隧道示例当成 OpenAI 官方推荐方案。

参考：OpenAI Developer mode and MCP apps 文档。

Cursor：mcp.json、工具开关与验证

导入：Cursor 官方支持项目级 .cursor/mcp.json 和全局 ~/.cursor/mcp.json。本地服务使用 command、args 和 env 配置。
开启：重新打开项目，在 Agent 或 Composer 的 Available Tools 中启用 Zotero 工具。Cursor 支持 stdio、SSE 和 Streamable HTTP，所选传输方式必须与服务端启动参数一致。
验证：先在工具列表确认服务在线，再让 Agent 搜索一个确定存在的标题。日志入口是工具列表、工具开关和聊天中的参数与响应展开区；Cursor CLI 还可使用 cursor-agent mcp list 和 cursor-agent mcp list-tools zotero 检查服务状态。

示例配置如下，具体命令仍以你选择的实现为准：

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

参考：Cursor MCP 文档、Cursor CLI MCP 命令文档。

Local、Web API 与 Hybrid：按问题选择

你的需求	优先模式	检查项目
只在当前电脑搜索本地库	Local read-only	Zotero 运行、本地通信开启、客户端能找到服务命令
在另一台设备访问同步库	Web API	API Key、Library ID、个人库或群组库类型、网络连通
本地读取、远程写入	Hybrid	本地变量与 Web API 凭据同时存在，确认项目支持该组合
Zotero 10+本地写入	仅在实现明确支持时使用	Zotero 官方 Local API 授权、写入确认和撤销路径

Zotero 官方文档说明，Zotero 10+的 Local API 支持写入，并通过运行时授权产生本地 API Key；该 Key 与 zotero.org Web API Key 无关，且不按库细分权限。若只需要读取，不要为了“以后可能写入”而提前开放写入权限。

54yyyu 项目提供 zotero-mcp authorize-local 及状态、撤销等命令，但这些是该项目的封装。richardjlyon 项目 README 仍说明其写入通过 Web API，不能把前者的本地写入命令套到后者。

常见报错：按最小范围定位

找不到 zotero-mcp：确认安装到了当前用户环境，并用绝对路径配置；GUI 客户端可能没有继承终端 PATH。
无法连接本地 API：打开 Zotero，确认“允许其他应用通信”已开启，再检查是否选错实现或端口。
API Key 无权限：区分 Web API Key 与 Local API Key；Web API 写入需要相应写权限，Local API Key 由 Zotero 运行时授权。
客户端不显示工具：重启客户端，检查 JSON 是否有效，确认服务进程能启动，再在客户端工具列表或 /mcp、cursor-agent mcp list 中核对。
搜索有结果但 PDF 为空：确认条目存在附件，PDF 是否有文本层；扫描件、复杂表格和公式可能需要额外 OCR 或页面图像处理，不能只重复重启 MCP。
写入失败：先用只读搜索确认连接，再检查实现所需的写入路径和权限。不要直接把 Web API Key 粘贴到公共仓库或聊天记录。

安全检查与首次成功验证清单

把 API Key 放在本机环境变量或受权限保护的配置中。
先完成只读验证，再开启写入；首次写入只选择测试条目或测试集合。
确认客户端显示的服务名称、项目仓库和命令是一一对应的。
对远程 HTTP、SSE 或隧道连接设置访问控制；没有认证的服务端点不要公开分享。
用固定记录模板保存结果：客户端、实现、模式、Zotero 版本、测试时间、搜索结果、附件读取、写入结果和错误原文。

可复制的测试顺序：

1. 搜索一个确定存在的标题
2. 读取条目作者、年份和 DOI
3. 列出该条目的附件
4. 读取 PDF 第 1 页或指定页面
5. 读取一条已有注释（若该实现支持）
6. 仅在确认权限后测试写入
7. 记录客户端工具列表与错误原文

按 2026-10 界面核对时，客户端菜单、套餐权限和 MCP 传输支持仍可能变化；遇到界面不一致，应以对应客户端官方文档和所选项目仓库当前说明为准。遵守所在地法律与服务条款。

常见问题

Zotero MCP 是 Zotero 官方插件吗？

不是。它通常指遵循 MCP 协议的独立服务端项目。本文涉及的两个实现分别来自公开 GitHub 仓库，不能称为 Zotero 官方插件；本站也与 Zotero 及这些项目无关联。

只读本地模式需要 Zotero API Key 吗？

54yyyu 项目的 Local read-only 模式文档写明不需要凭据，但需要 Zotero 正在运行并开启允许其他应用通信。其他实现的要求可能不同，应以各自文档为准。

Zotero 7+能不能直接本地写入？

不能这样概括。54yyyu 文档把 Zotero 7+列为本地 API 与全文访问条件；Zotero 官方文档把本地写入授权列为 Zotero 10+能力。版本、实现和写入路径必须分开判断。

为什么 AI 能看到条目，却读不了 PDF？

条目元数据和附件全文是不同层级。PDF 可能没有文本层、附件权限不足，或实现尚未完成全文索引。先列出附件，再读取单页；扫描 PDF 还要单独核对 OCR 条件。

API Key 应该给读取权限还是写入权限？

只读工作流优先使用读取权限；只有确实需要创建、修改或删除数据时才申请写入权限。Zotero 官方文档明确要求 Web API 写请求使用具有写入权限的 API Key。

ChatGPT 能直接连接本机 Zotero MCP 吗？

OpenAI 官方文档说明 ChatGPT 连接的是远程 MCP Server，不能直接连接只在本机运行的服务。需要使用工作区允许的远程 MCP 应用配置，并先评估远程暴露的数据风险。

Cursor 的 MCP 配置放在哪里？

Cursor 官方支持项目级的 <code>.cursor/mcp.json</code> 和全局的 <code>~/.cursor/mcp.json</code>。项目级适合只对当前代码库启用，全局配置则对多个项目生效。

如何判断是客户端问题还是 MCP Server 问题？

先在终端单独启动或检查服务，再看客户端是否列出工具。终端能启动但客户端没有工具，多半是配置路径、PATH、JSON 或传输方式问题；服务本身启动失败，则先处理实现依赖和 Zotero 本地连接。