zotero-library-mcp

zotero-library-mcp

一个 MCP 服务，可让 Claude、Codex 和 ChatGPT 通过 DOI、arXiv ID 或 ISBN 将论文和书籍添加到你的 Zotero 文库，并管理你的分类、标签和条目。

该服务支持这些客户端使用的两种 MCP 传输方式：

• stdio（默认），适用于 Claude Code、Claude Desktop、Codex CLI/IDE 和 ChatGPT 桌面应用
• Streamable HTTP，适用于托管的 ChatGPT 应用或任何远程 MCP 客户端

工具

添加论文

• add_paper_by_doi — 通过 CrossRef 解析 DOI，并将论文添加到 Zotero（会检测重复项）
• add_papers_by_dois — 一次最多批量添加 50 篇论文
• add_paper_by_arxiv_id — 通过 arXiv ID 添加预印本（有 DOI 时使用 DOI，否则使用 arXiv 元数据）
• add_item_from_metadata — 根据经过验证的手动元数据创建任意受支持的 Zotero 条目类型

添加书籍

• add_book_by_isbn — 通过 Open Library 解析 ISBN，并将书籍添加到 Zotero（会检测重复项）

搜索与浏览

• list_libraries — 查找 API 密钥所有者的个人文库和共享群组文库，并显示其 ID 和密钥权限
• search_library — 按标题、作者、标签等搜索 Zotero 文库；支持通过 start/limit 分页（精确搜索无结果时会回退到模糊匹配）
• get_item_details — 查看任意条目的完整元数据
• get_recent_items — 列出最近添加的条目
• get_unfiled_items — 获取未归入任何分类的条目
• search_fulltext — 搜索 Zotero 元数据和已编入索引的全文
• find_duplicates — 按 DOI、ISBN 或规范化标题查找重复条目
• list_attachments — 列出所有附件并选择特定的 PDF 密钥
• health_check — 验证文库凭据、访问权限和存储配置

阅读与批注

• get_item_fulltext — 从 Zotero 索引或 PDF 返回长度受限的纯文本，不泄露临时路径
• get_bibtex — 以只读方式导出条目、分类或整个文库的 BibTeX/BibLaTeX
• save_bibtex — 将导出内容保存到获准的本地路径
• get_annotations — 列出论文 PDF 上的所有高亮和批注
• create_annotation — 在 PDF 中高亮一段文本（搜索确切文本，在 Zotero 阅读器中创建可见高亮，并返回预览图像以供验证）。智能处理重叠：完全重复时会更新现有评论；子段落则会自动使用对比色高亮。
• add_note — 为条目添加笔记
• list_notes、update_note、delete_note — 管理现有笔记
• update_annotation、delete_annotation — 编辑或删除批注

文件附件

• attach_file — 通过 stdio 附加本地文件，或通过 HTTP 附加 ChatGPT 文件输入
• download_pdf — 返回适用于远程环境的 MCP 文件资源
• save_pdf — 将 PDF 保存到获准的本地路径

分类

• list_collections — 列出所有分类（包括嵌套分类）
• create_collection — 创建新分类（可选择嵌套在父分类下）
• get_collection_items — 浏览分类中的条目，支持通过 start/limit 分页
• add_to_collection — 将现有条目添加到分类
• remove_from_collection — 从分类中移除条目（条目仍保留在文库中）
• rename_collection、move_collection — 重新整理分类

标签

• list_tags — 列出文库中的所有标签
• add_tags — 为条目添加一个或多个标签（可选颜色）
• remove_tags — 从条目中移除标签
• delete_tags — 从整个文库中删除标签
• set_tag_color — 为标签指定颜色（显示在 Zotero 的标签选择器中）
• rename_tag — 重命名文库中所有条目上的某个标签
• unset_tag_color — 移除标签颜色，但不删除标签

验证

• verify_items — 通过 CrossRef 重新检查近期条目，发现错误的 DOI 或标题不匹配问题

删除

• delete_item — 从你的文献库中永久删除条目
• delete_collection — 永久删除集合
• trash_item、restore_item — 日常清理时，优先使用可撤销的移入回收站操作

该服务还提供标准的只读 search 和 fetch 工具形式，供 ChatGPT 公司知识和深度研究使用。

前置条件

1. 一个 Zotero 账户
2. 具有写入权限的 Zotero API 密钥：https://www.zotero.org/settings/keys
3. 你的 Zotero 文献库 ID（显示在同一页面或个人资料 URL 中）
4. 已安装 uv

快速开始

Codex 和 ChatGPT 桌面应用

Codex 和 ChatGPT 桌面应用在同一台 Codex 主机上共用 MCP 配置。只需添加一次服务：

codex mcp add zotero \
  --env ZOTERO_LIBRARY_ID=your_library_id \
  --env ZOTERO_API_KEY=your_api_key \
  -- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

然后重启 Codex 或 ChatGPT 桌面应用。在 Codex 中，使用 /mcp 确认 zotero 已连接。在 ChatGPT 桌面应用中，打开设置 → MCP 服务查看同一服务。

要使用 WebDAV 存储，请添加 WebDAV 示例中显示的三个 ZOTERO_WEBDAV_* 值。如果桌面应用找不到 uvx，请将其替换为 which uvx 返回的完整路径。

你也可以直接在 ~/.codex/config.toml 中配置该服务：

[mcp_servers.zotero]
command = "/full/path/to/uvx"
args = ["--from", "git+https://github.com/RaulSimpetru/zotero-library-mcp", "zotero-mcp"]
env_vars = ["ZOTERO_LIBRARY_ID", "ZOTERO_API_KEY", "ZOTERO_LIBRARY_TYPE", "CROSSREF_MAILTO", "ZOTERO_WEBDAV_URL", "ZOTERO_WEBDAV_USER", "ZOTERO_WEBDAV_PASSWORD"]
startup_timeout_sec = 30
tool_timeout_sec = 120

使用 env_vars 时，请在包含这些变量的环境中启动 Codex/ChatGPT。如果你有意将变量值存储在配置文件中，请改用 [mcp_servers.zotero.env]。

Claude Code

将其作为插件安装（推荐）：

/plugin install zotero --marketplace RaulSimpetru/zotero-library-mcp

对于较旧版本的 Claude Code，请先运行 /plugin marketplace add RaulSimpetru/zotero-library-mcp，然后运行 /plugin install zotero@zotero-library-mcp。启用插件时，Claude Code 会询问你的文献库 ID 和 API 密钥（以及可选的 WebDAV 和 Unpaywall 设置），并将 API 密钥和 WebDAV 密码保存在系统钥匙串中。要获取新版本，请运行 /plugin marketplace update zotero-library-mcp，或在 /plugin 中开启该市场的自动更新。

插件工具的名称为 mcp__plugin_zotero_zotero__<tool>，而不是 mcp__zotero__<tool>；请更新所有引用旧工具名称的权限规则。如果你之前通过 claude mcp add 添加了该服务，请删除该条目（claude mcp remove zotero -s user），以免两个副本同时运行。

或者，将其添加为普通 MCP 服务：

claude mcp add zotero \
  -e ZOTERO_LIBRARY_ID=your_library_id \
  -e ZOTERO_API_KEY=your_api_key \
  -- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

WebDAV 设置

要使用 WebDAV 文件存储（例如 Synology、Nextcloud），请添加 WebDAV 变量：

claude mcp add zotero \
  -e ZOTERO_LIBRARY_ID=your_library_id \
  -e ZOTERO_API_KEY=your_api_key \
  -e ZOTERO_WEBDAV_URL=https://your-webdav-server.com \
  -e ZOTERO_WEBDAV_USER=your_username \
  -e ZOTERO_WEBDAV_PASSWORD=your_password \
  -- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "zotero": {
      "command": "/full/path/to/uvx",
      "args": ["--from", "git+https://github.com/RaulSimpetru/zotero-library-mcp", "zotero-mcp"],
      "env": {
        "ZOTERO_LIBRARY_ID": "your_library_id",
        "ZOTERO_API_KEY": "your_api_key",
        "ZOTERO_WEBDAV_URL": "https://your-webdav-server.com",
        "ZOTERO_WEBDAV_USER": "your_username",
        "ZOTERO_WEBDAV_PASSWORD": "your_password"
      }
    }
  }
}

注意： Claude Desktop 不会继承 shell 的 PATH，因此你需要使用 uvx 的完整路径。在终端中运行 which uvx 即可查找。

网页版 ChatGPT（Apps SDK / 开发者模式）

网页版 ChatGPT 连接到 HTTPS Streamable HTTP 端点。使用 HTTP 传输在本地启动服务，然后通过 Secure MCP Tunnel 或其他经过身份验证的 HTTPS 部署方式使其可访问：

ZOTERO_LIBRARY_ID=your_id ZOTERO_API_KEY=your_key \
  uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --allowed-host your-tunnel.example.com

MCP 端点为 https://your-tunnel.example.com/mcp。在 ChatGPT 中启用开发者模式，创建开发者模式应用，并将该 URL 填入 MCP 服务 URL。有关当前的界面操作流程，请参阅 OpenAI 的从 ChatGPT 连接指南。

安全性： 最安全的个人设置是使用 OpenAI Secure MCP Tunnel，并将 MCP 服务绑定到 loopback。HTTP 模式默认会禁用所有服务路径的读取和写入。attach_file 接受 ChatGPT 授权的文件对象，而 download_pdf 返回不透明的 MCP 资源链接。安全注释只是审批提示，并非授权边界。

对于公共部署，请配置外部 OAuth 2.1 身份提供商。服务会根据其 JWKS 端点验证 JWT 访问令牌：

export ZOTERO_MCP_OAUTH_ISSUER=https://auth.example.com
export ZOTERO_MCP_OAUTH_RESOURCE=https://zotero.example.com
export ZOTERO_MCP_OAUTH_JWKS_URL=https://auth.example.com/.well-known/jwks.json
export ZOTERO_MCP_OAUTH_SCOPES=zotero:read,zotero:write

授权服务器必须发布 OAuth/OIDC 发现元数据，支持使用 PKCE 的 MCP OAuth 2.1 流程，为 ZOTERO_MCP_OAUTH_RESOURCE 颁发令牌，并包含已配置的作用域。请参阅 OpenAI 的身份验证指南。仅用于在已完成身份验证的网关后进行测试时，--allow-unauthenticated-http 明确表示你接受未经过身份验证的非 loopback 监听器。

此流程仍使用一个服务端 Zotero API 密钥。每个经过身份验证的 MCP 客户端都可以访问该密钥可用的文库，包括共享群组。请使用仅包含这些客户端所需文库权限的密钥。真正的多用户服务必须将经过验证的 OAuth 身份映射到单独的 Zotero 凭据，并实施按用户授权；这种部署架构有意不纳入此个人服务包。

如果 HTTP 部署确实需要服务路径，请仅在受限根目录中启用：

zotero-mcp --transport streamable-http \
  --allow-server-files \
  --file-root /srv/zotero-mcp/exports

HTTP 启动设置也可以通过环境变量提供：

CLI 选项	环境变量	默认值
--transport	ZOTERO_MCP_TRANSPORT	stdio
--host	ZOTERO_MCP_HOST	127.0.0.1
--port	ZOTERO_MCP_PORT 或 PORT	8000
--http-path	ZOTERO_MCP_HTTP_PATH	/mcp
--allowed-host	ZOTERO_MCP_ALLOWED_HOSTS（逗号分隔）	本地主机
--allowed-origin	ZOTERO_MCP_ALLOWED_ORIGINS（逗号分隔）	本地来源
--stateless-http	ZOTERO_MCP_STATELESS_HTTP	false
--allow-unauthenticated-http	ZOTERO_MCP_ALLOW_UNAUTHENTICATED_HTTP	false
--allow-server-files	ZOTERO_MCP_ALLOW_SERVER_FILES	HTTP 模式下为 false
--file-root	ZOTERO_MCP_FILE_ROOTS（逗号分隔）	无

独立运行

ZOTERO_LIBRARY_ID=your_id ZOTERO_API_KEY=your_key \
  uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

个人库和共享群组库

环境变量用于选择默认库。省略库参数的现有调用仍会使用该默认库。

调用 list_libraries() 可查找密钥所有者的个人库和共享群组。结果包括 name、library_id、library_type、is_default 和 key_permissions。群组结果会通过 limit 和 start 分页；请持续获取 next_start，直到其值为 null。即使默认库是群组，也可以进行发现。

其他每个工具都接受可选的 library_id 和 library_type 参数：

list_libraries()
list_collections(library_id="123456", library_type="group")
search_library(query="ultrasound", library_id="123456", library_type="group")
get_item_details(item_key="<key from that group>", library_id="123456", library_type="group")
search_library(query="ultrasound")  # Uses the configured default again

同时传入两个参数以选择一个库，或两个都省略。请使用 list_libraries 返回的 ID，而不是群组名称。选择仅对单次调用生效，不会更改环境或其他客户端的目标，包括并发调用。条目和集合的键必须来自所选库。Zotero 会强制执行 API 密钥的权限和用户的群组权限；群组请求被拒绝时会失败，不会回退到个人库。health_check 接受相同参数，可在不写入数据的情况下验证特定库。

群组附件使用 Zotero 内置存储。只有配置的个人库使用 WebDAV，即使同一服务器也会访问共享群组。

环境变量

变量	必需	说明
ZOTERO_LIBRARY_ID	是	默认 Zotero 用户库或群组库 ID
ZOTERO_API_KEY	是	具有读写权限的 API 密钥
ZOTERO_LIBRARY_TYPE	否	默认库类型：user（默认）或 group
CROSSREF_MAILTO	否	用于 CrossRef 礼貌池的电子邮箱（可加快 API 访问速度）
UNPAYWALL_EMAIL	否	用于查找开放获取 PDF 的联系邮箱（默认为 CROSSREF_MAILTO）
ZOTERO_WEBDAV_URL	否	用于文件存储的 WebDAV URL（例如 https://dav.example.com）
ZOTERO_WEBDAV_USER	否	WebDAV 用户名
ZOTERO_WEBDAV_PASSWORD	否	WebDAV 密码
ZOTERO_MCP_OAUTH_ISSUER	否	受保护 HTTP 部署使用的外部 OAuth/OIDC 颁发者 URL
ZOTERO_MCP_OAUTH_RESOURCE	否	规范的 HTTPS MCP 资源/受众 URL
ZOTERO_MCP_OAUTH_JWKS_URL	否	用于验证 JWT 访问令牌的 JWKS URL
ZOTERO_MCP_OAUTH_SCOPES	否	以逗号分隔的必需作用域（默认为读和写）
ZOTERO_MCP_FILE_ROOTS	否	启用 HTTP 服务器路径时允许访问的根目录（以逗号分隔）

注意： 如果设置了全部三个 ZOTERO_WEBDAV_* 变量，配置的个人库中的附件将使用 WebDAV，而非 Zotero 内置存储。群组附件始终使用 Zotero 存储。服务器会自动在 WebDAV 基础 URL 后追加 /zotero，与 Zotero Desktop 的行为一致。

版本 0.10.2

• 安装为 Claude Code 插件：/plugin install zotero --marketplace RaulSimpetru/zotero-library-mcp。
• 现在，空的 ZOTERO_LIBRARY_TYPE 表示使用默认值（user），因为插件安装会将未设置的可选项作为空字符串传入。

版本 0.10.1

• 再次支持将文件附加到 Zotero 存储空间（群组文库和未配置 WebDAV 的设置）：Zotero 会拒绝 Pyzotero 发送的完整本地路径作为文件名。现在会确认上传结果，并在上传受速率限制或失败时报告错误，而不是留下空附件。
• list_tags 会返回所有标签；Zotero 的标签分页元数据在标签超过 200 个时有误，导致旧版列表遗漏其余标签。
• 剩余的查询参数不再在调用之间泄漏（例如，获取条目模板后进行重复项检查时，只会搜索该类型的条目）。
• 搜索和重命名标签时，即使包含单词 "tags" 也不再崩溃。
• 现在可以对已移入回收站的条目添加标签、归档，以及编辑笔记或批注。
• 高亮现在能正确显示在带偏移裁剪框的旋转页面上，会匹配完整单词，仅在同一位置检查重复项；如果缺少 occurrence，会报告错误，而不是高亮其他段落。
• arXiv 导入会检测论文任意版本的已有副本。
• CrossRef 导入会保留机构作者和编辑，并将图书、编著图书、章节和学位论文映射为正确的条目类型；Open Library 图书会从作品记录中获取作者信息。
• verify_items 支持 DataCite DOI（arXiv、Zenodo）、CrossRef 标题中的 HTML 和副标题；health_check 会将只读密钥报告为 write_access: false。
• BibTeX 导出会保留 Zotero 中的顺序，并确保跨页 citekey 唯一。
• 子条目列表（附件、笔记、批注）不再受限于 100 个；会跳过链接的 PDF，并且可以读取独立 PDF。
• 现在可以移除最后一个标签颜色；拒绝删除包含 || 的标签。
• 加强了托管 HTTP 部署的安全性：下载会连接到经过验证的 IP（防止 DNS 重绑定），JWKS 重新获取受到速率限制，文件保存使用独占临时文件。
• DOI 导入不再创建重复项。 Zotero 的搜索不会索引 DOI，因此旧的检查无法匹配；现在导入会搜索解析后的标题并比较 DOI（包括 Extra 中的 DOI: 行）。
• ISBN 导入不再为使用带连字符 ISBN 存储的图书创建重复项；现在 ISBN-10 和 ISBN-13 格式可以相互匹配。
• search_library 会返回论文，而不是匹配附件和笔记。
• 受速率限制的写入操作绝不会重试（重试可能会重复创建条目），现在会失败，而不是报告成功。
• add_papers_by_dois(attach_pdfs=True) 会并行下载 PDF。
• search_fulltext 和 search 会查询顶层条目（速度约快 20 倍）。
• 模糊搜索和 find_duplicates 会复用文库缓存，并通过 Zotero 的增量同步（since=）保持缓存最新，因此重复调用耗时远低于一秒。
• 当未设置 CROSSREF_MAILTO 时，CrossRef 请求会使用 UNPAYWALL_EMAIL 作为礼貌池联系人，并在请求受速率限制时重试。
• create_annotation 会完整高亮跨行的引文，在多页范围内统计 occurrence，并使用 PDF 自带的页码标签。
• 在 DOI/arXiv 导入期间附加的 PDF 会使用条目标题命名，结果现在也会说明未附加 PDF 的原因。
• 列表输出会为 12/1/1993 这类日期显示正确的年份。
• health_check 会以 user/group 的形式返回 library_type，并报告是否已配置开放获取 PDF 查询（UNPAYWALL_EMAIL）。
• 新增 list_trash 工具，用于查找要传递给 restore_item 的键。
• 加快了按条目键调用 get_bibtex、rename_tag、get_recent_items、模糊搜索和 find_duplicates 的速度；Zotero API 连接会在多次调用间复用。
• 全文库和集合的 get_bibtex 导出在超过 max_chars 后会停止下载。
• get_item_fulltext 会优先使用 PDF 的索引，而非网页快照的索引。
• find_duplicates 会报告 items_scanned 和 scan_capped。
• 当条目没有 URL 时，search 会回退到该条目的 zotero.org 链接。
• 缩短了工具说明；服务器说明中会统一解释文库目标的设置。

版本 0.10.0

• 使用 list_libraries 发现个人和共享文库。
• 每次调用工具时，使用 library_id 和 library_type 指定文库； 现有调用会继续使用配置的默认文库。
• 确保并发调用和嵌套导出都限定在所选文库内。
• 共享文库附件使用 Zotero 存储；个人 WebDAV 仅用于配置的个人文库。
• 确保当前依赖项导入和 HTTP 日志记录与 MCP stdio 兼容。

升级后请重启 MCP 连接，以加载新的工具架构。

升级到 0.8

为便于远程客户端应用正确的安全审批，两个写入路径的操作已从对应的只读操作中拆分出来：

• get_bibtex(save_path=...) 现已改为 save_bibtex(save_path=...)；get_bibtex 仅返回数据。
• download_pdf(save_path=...) 现已改为 save_pdf(save_path=...)；download_pdf 会返回一个不透明的 MCP 资源链接。

对 get_bibtex 和 download_pdf 的现有只读调用仍可继续使用。

0.8.1

• PDF 和批注预览资源在客户端读取时，现在会保留其精确 MIME 类型。
• PDF 下载会报告进度，并在 WebDAV 超时时返回清晰的错误信息。
• health_check 会报告 API 密钥的写入权限，但不会修改文库。
• 服务器说明已缩短，减少客户端重复使用上下文。

工作原理

1. 提供 DOI、arXiv ID 或 ISBN
2. 服务端查询相应 API 以获取完整元数据：
   • DOI → CrossRef API
   • arXiv ID → arXiv API（存在 DOI 时回退到 CrossRef）
   • ISBN → Open Library API
3. 将元数据映射为 Zotero 条目格式（标题、作者、期刊／出版商、日期等）
4. 通过 Zotero Web API 在你的 Zotero 文库中创建条目

许可证

MIT

mcp-name: io.github.RaulSimpetru/zotero-library-mcp