Zotero Native MCP

Name: Zotero Native MCP
Author: dvdsosa

本地服务

github.com/dvdsosa生产力121 周前更新

代码仓库

关于 Zotero Native MCP

Zotero Native MCP 是面向 Zotero 10 及以上版本的本地 MCP 服务，可读取和修改文献库。它通过 Zotero 本地 API 提供检索、全文、文献和附件操作，无需插件、Web API 密钥或云端访问。

主要功能

01检索文献条目并读取 PDF 全文
02创建和管理分类与文献
03附加本地 PDF 文件
04从 Zotero 回收站恢复已删除条目
05查看文库、标签和已保存搜索

适用场景

01查找资料并搜索 PDF 内容
02将文献整理到分类中
03添加文献并附加磁盘中的 PDF

MCP 相关

它向 MCP 客户端提供 28 个 Zotero 工具，涵盖条目检索与编辑、分类管理、全文访问、附件处理和文库状态查询。操作通过本地 Zotero 应用执行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "dvdsosa-zotero-native": {
      "command": "npx",
      "args": [
        "-y",
        "zotero-native-mcp"
      ],
      "env": {
        "ZOTERO_LOCAL_PORT": "<ZOTERO_LOCAL_PORT>",
        "ZOTERO_LOCAL_APP_NAME": "<ZOTERO_LOCAL_APP_NAME>"
      }
    }
  }
}

启动命令npx -y zotero-native-mcp

需要配置的环境变量

ZOTERO_LOCAL_PORTPort of Zotero's local HTTP server. Defaults to 23119.

ZOTERO_LOCAL_APP_NAMEName shown in Zotero's authorization dialog. Defaults to zotero-native-mcp.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmzotero-native-mcp1.0.2stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

zotero-native-mcp

一个可读取并写入 Zotero 10+ 文献库、完全离线运行的 MCP 服务。

将 Zotero 连接到 Claude、Claude Code、Cursor 或任何 Model Context Protocol 客户端。你的助手可以搜索文献库、读取 PDF 全文、创建分类、添加参考文献，以及附加磁盘中的 PDF。

所有操作都通过 127.0.0.1 在 Zotero 应用中执行。无需 zotero.org 账号。无需 Web API 密钥。无需 Zotero 插件。无需往返云端。

Claude 将一篇论文归档到 Zotero 分类中，然后通过 zotero-native-mcp 重命名文献库中的 290 个标签

为什么要开发这个项目

Zotero 10 为其内置本地 API 增加了写入支持。在此之前，每个 Zotero MCP 服务都必须绕过只读的本地端点：要么通过 api.zotero.org 路由写入操作（速度慢、需要 API 密钥，还需要将文献库同步到云端），要么提供单独的 Zotero 插件供你安装并保持更新。

本服务直接使用原生功能。无需在 Zotero 中安装任何东西，无需管理凭据；由于不会访问网络，读取操作只需 8–60 ms。

标准	Web API 服务	基于插件的服务	zotero-native-mcp
可离线运行	❌	✅	✅
需要 zotero.org API 密钥	✅ 必需	❌	❌
需要 Zotero 插件（`.xpi`）	❌	✅ 必需	❌
创建分类	✅	✅	✅
附加本地 PDF	⚠️ 通过云端	✅	✅
典型读取延迟	500–1500 ms	<50 ms	8–60 ms

要求

Zotero 10 或更高版本，且正在运行。这是硬性要求，并非建议：Zotero 10 之前不存在通过本地 API 写入的功能。在 Zotero 7–9 上，读取工具可以工作，但所有写入操作都会失败。
Zotero → 设置 → 高级 → 启用 “允许此计算机上的其他应用程序与 Zotero 通信”。
Node.js 22 或更高版本。Node 20 已于 2026 年 4 月结束生命周期。

已测试环境

以下内容陈述的是已验证的情况，而非预期结果。其他平台和客户端预计也能正常工作。本服务使用便携的 TypeScript 编写，通过 127.0.0.1 通信，设计上不包含任何特定平台的代码。但这些平台和客户端尚未经过验证，本表如实列出了已验证的范围。

组件	已验证环境
操作系统	macOS 26.6（Apple Silicon）、Windows 11 Pro build 26200（x64）和 Ubuntu 24.04 LTS（x86_64），三种系统均使用真实的 Zotero 进行测试
Zotero	10.0.1
Node.js	分别为 26.8、22.23 和 24.16；CI 测试覆盖 22、24 和 26
MCP 客户端	Claude Code 2.1，在 macOS 和 Windows 上测试
文献库	个人文献库和群组文献库；在两者中均测试了全部 28 个工具

CI 在 Linux、macOS 和 Windows × Node 22、24 和 26 的矩阵中运行单元测试和模拟协议测试，因此代码本身在这三个平台上的可移植性均已覆盖。但任何 CI 运行环境都无法测试与真实 Zotero 的交互，因为那里没有安装 Zotero。这部分是手动完成的：scripts/coverage.mjs 在所有三个操作系统上，通过正在运行的文献库测试了全部 28 个工具。

尚未验证。 Intel Mac；Linux 上的 Claude Code（仅运行了脚本）；任何平台上的 Claude Desktop、Cursor 和其他 MCP 客户端。

如果你在此列表以外的环境中运行本服务，欢迎反馈结果，无论成功与否。此类反馈是本项目目前最需要的信息。

请先备份你的文献库

警告

此服务可以修改和删除 Zotero 文献库中的条目。 开始前请先备份，并定期备份。

默认情况下，删除操作可以撤销：zotero_delete_items 和 zotero_delete_collection 会将内容移至 Zotero 的回收站，你可以在 Zotero 窗口中恢复，也可以使用 zotero_restore_items 恢复。但 Zotero 会在 30 天后自动清空回收站，而且这两个工具都接受 permanent: true 参数，可直接彻底删除内容，无法撤销，附件文件也会从磁盘中移除，没有任何 API 可以将它们恢复。zotero_empty_trash 会对回收站中的所有内容执行同样的操作。

这些工具由助手根据自然语言指令驱动，可能会误解你指的是哪个条目。

备份方法： 退出 Zotero，然后复制整个数据目录：macOS 和 Linux 上是 ~/Zotero， Windows 上是 %USERPROFILE%\Zotero，也可以查看 设置 → 高级 → 文件和文件夹 中显示的路径。该目录包含 zotero.sqlite 和存放所有附件的 storage 文件夹。Zotero 官方指南见 zotero.org/support/zotero_data。

与 zotero.org 同步不等于备份：删除操作也会同步。

本软件按“现状”提供，不附带任何形式的保证，作者对数据丢失不承担任何责任。请参阅 LICENSE。

快速开始

claude mcp add --scope user zotero-native-mcp -- npx -y zotero-native-mcp

其他客户端（Claude Desktop、Cursor、……）

{
  "mcpServers": {
    "zotero-native-mcp": {
      "command": "npx",
      "args": ["-y", "zotero-native-mcp"]
    }
  }
}

--scope user 会为所有项目注册服务。不加此参数时，claude mcp add 默认使用 local 范围，会将服务绑定到运行命令的那个目录；打开其他目录时，工具就不会出现。

无需设置环境变量。启动新会话，然后让你的助手运行 zotero_status，以确认连接正常。

工具首次写入时，Zotero 会弹出对话框，询问是否允许。选择 “始终允许”，这样之后就不会再询问。

文档

文档	内容
📚 教程	初次使用？十分钟内完成安装，并将一篇论文连同 PDF 一起归档。
🔧 操作指南	附加 PDF · 群组文献库 · 从其他 Zotero MCP 迁移 · 恢复已删除内容 · 故障排除
📖 参考手册	全部 28 个工具、参数、输出、限制和环境变量。
💡 说明	架构 · 链接附件与导入附件 · 授权机制
🛠 参与贡献	开发环境配置、73 项测试套件，以及针对运行中的 Zotero 测试每个工具。

工具一览

文献库：list_collections get_collection create_collection update_collection delete_collection restore_collection

条目：search_items get_item get_item_children create_items update_item delete_items restore_items add_items_to_collection remove_items_from_collection get_item_fulltext export_items

回收站：list_trash empty_trash（以及上方的 restore_* 工具）

附件：attach_file get_attachment_path

发现：list_tags list_saved_searches run_saved_search

系统：status authorize list_libraries get_item_type_fields

所有名称都带有 zotero_ 前缀。完整签名请参阅**参考手册**。

先前工作

本项目并非分叉项目。Zotero 10 支持原生本地写入后，本项目从头编写而成；但它借鉴了早期在限制更多的条件下解决同一问题的项目：

54yyyu/zotero-mcp：使用最广泛的 Zotero MCP 服务。功能丰富，包括语义搜索；写入通过 api.zotero.org 完成。
cookjohn/zotero-mcp：Zotero 7 插件，可在 Zotero 内部提供 MCP 端点，并支持向量搜索。
Ayanya-0628/zotero-mcp 和 dzackgarza/zotero-local-write-api：通过配套的 .xpi 写入端点实现本地优先写入。
kujenga/zotero-mcp：用于 Zotero API 的轻量级 Python 服务。

如果你需要支持 Zotero 7/8/9、语义或向量搜索，或者需要写入只能通过云端访问的文库，那么这些项目仍然是合适的选择。

贡献

欢迎提交问题和拉取请求。CI 必须在 Linux、macOS 和 Windows 上通过，并覆盖 Node 22、24 和 26。

请参阅 CONTRIBUTING，了解开发环境设置、测试套件，以及用于针对实时 Zotero 测试每个工具的脚本。

许可证

_{关键词：Zotero MCP 服务 · Model Context Protocol · Zotero Claude 集成 · Zotero 本地 API · 离线文献管理器自动化 · Zotero AI 助手 · BibTeX 导出 · 学术研究工具 · Claude Code Zotero · Cursor Zotero}

支持 Markdown

登录后评论