AI导哈

Zotero本地MCP服务器

一个本地优先的Zotero MCP服务器，用于搜索和阅读图书馆、读取PDF文本并收集页面级证据，以及写入图书馆（添加/更新/删除项目、管理集合/标签/笔记）——所有操作均在运行Zotero桌面应用程序的本地地址`127.0.0.1:23119`上进行，而非云API。

  • by Ayanya-0628
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Ayanya-0628/zotero-mcp

使用说明

佐特罗当地mcp

Zotero的本地第一台MCP服务器：搜索和阅读您的库，阅读PDF文本和 收集页面级证据，以及 写 添加/更新/删除项目， 管理收藏/标签/笔记）——所有这些都是针对正在运行的Zotero桌面应用程序 127.0.0.1:23119，从来没有云API。

阅读使用Zotero的本地 /api （具有SQLite读取回退）。 写 穿过a 小型配套插件， Zotero写入端点 （in zotero-write-endpoint/), 因为Zotero的官方本地API是只读的(POST/PATCH/DELETE → 405/501). The 插件通过Zotero自己的插件执行进程内的每次写入 item.saveTx() --安全，无直接 SQLite在Zotero打开时编写和工作。

版本控制

  • 变更日志： CHANGELOG.md
  • 首次发布说明： RELEASE_NOTES_v1.0.0.md

工具

搜索和阅读

  • health_check：验证Zotero路径、本地API可用性、DB可读性
  • list_collections：列出文件夹/收藏树
  • list_items：列出收藏中的书目项目
  • search_items：在整个库中搜索（筛选器： yearFrom/yearTo, authorIncludes, collectionKey)
  • search_by_doi：按确切的DOI查找项目（之前使用 add_by_doi 避免重复）
  • search_by_tag：使用可选的集合筛选器按包含/排除标签进行搜索
  • ask_zotero_nl：自然语言查询；自动提取年份过滤器并扩展CN→EN术语
  • get_recent：最近修改的顶级项目
  • get_tags：列出可用标记
  • get_item_children：项目的子注释/附件/注释
  • get_annotations：项目的注释
  • notes：全局或父项下列出/搜索笔记
  • export_citations：项目的格式化引用
  • list_items_missing_pdf：没有PDF附件的项目

PDF和证据

  • read_pdf_pages：从本地PDF的特定页面读取文本（否 .txt 输出）
  • find_claim_evidence：输入索赔→ 具有重复数据消除页面级PDF的排名论文 证据摘要和格式引用
  • import_pdf：通过Zotero导入本地PDF 连接器 编写API（自动识别 元数据、可选的收集归档）。用途 /connector/*，而不是写插件。

写——需要 Zotero写入端点 插件（见下文）

  • add_by_doi：按DOI添加项目（通过CrossRef获取元数据）
  • add_item_manual：从显式字段创建项目
  • update_item：更新现有项目的字段/创建者/标签
  • delete_item：删除项目
  • add_to_collection / remove_from_collection：归档/取消填充项目
  • create_collection：创建集合（可选嵌套）
  • add_tag / remove_tag：管理项目的标签
  • add_note_to_item：附上儿童便条
  • attach_url：附加链接的URL

如果没有安装插件，写入工具会返回一个明确的错误，说明 官方的本地API是只读的，插件是必需的。

先决条件

  • Node.js 20+
  • Zotero桌面应用程序正在运行，并带有“允许此计算机上的其他应用程序 与Zotero通信”已启用（设置→ 高级）
  • 本地Zotero数据目录（默认： %USERPROFILE%\Zotero)

安装（服务器）

npm install
npm run build

编写支持--安装配套插件

书写工具需要 Zotero写入端点 插件，注册 /zotero-write/* 在Zotero的内置服务器上。与Zotero 7/8/9兼容。

  1. 下载最新 zotero-write-endpoint.xpi 从 plugin-latest 释放 （或构建它 zotero-write-endpoint/).
  2. Zotero→ 工具→ 插件→ ⚙ → 从文件安装插件… → 选择 .xpi → 重启Zotero。
  3. 验证： curl http://127.0.0.1:23119/zotero-write/version.

插件 自动更新 从 plugin-latest 释放（its update_url 点在那里）， 因此，安装后，您可以通过Zotero的正常更新提示获得未来版本。看 zotero-write-endpoint/README.md 对于端点列表 以及发布/构建步骤。

Zotero 9注意：一个插件的 manifest.json 必须 包括 applications.zotero.update_url，或安装失败并产生误导 “与此版本不兼容”错误。

快速开始

git clone https://github.com/Ayanya-0628/zotero-mcp.git
cd zoteromcp
npm install
npm run build
  1. .mcp.json （项目层面）包括用于当地发展。
  2. 可选：复制 .env.example → .env 并设置自定义Zotero路径。
  3. 在您的MCP客户端中，确认 zotero-local 已加载。
  4. 跑 health_check那么 list_collections / search_items.
  5. 对于写入，请安装配套插件（如上）。

运行（stdio MCP，手动）

npm start

环境变量

  • ZOTERO_DATA_DIR （默认值： %USERPROFILE%\Zotero)
  • ZOTERO_DB_PATH （默认值： ${ZOTERO_DATA_DIR}\zotero.sqlite)
  • ZOTERO_STORAGE_DIR （默认值： ${ZOTERO_DATA_DIR}\storage)
  • ZOTERO_API_BASE_URL （例如。 http://127.0.0.1:23119/api)
  • MCP_DEBUG (1/true/on 打印API检测和回退日志）
  • MCP_MAX_PDF_MB （用于解析的最大PDF大小，默认值 120)

看 .env.example.

MCP客户端配置

项目级别(.mcp.json，在此仓库中发货）：

{
  "mcpServers": {
    "zotero-local": { "command": "node", "args": ["dist/index.js"], "cwd": "." }
  }
}

用于其他项目的绝对路径配置（避免 cwd 歧义）：

{
  "mcpServers": {
    "zotero-local": {
      "command": "node",
      "args": ["C:/path/to/zoteromcp/dist/index.js"],
      "env": { "ZOTERO_DATA_DIR": "C:/Users/yourname/Zotero" }
    }
  }
}

建筑说明

  • 读取：佐特罗当地 /api （自动检测到 127.0.0.1:23119 / localhost:23119), 使用SQLite读取回退。
  • 写：路由到 Zotero写入端点 插件的 /zotero-write/* 端点， 哪个电话 item.saveTx() 正在进行中。服务器从不编辑 zotero.sqlite 直接。
  • import_pdf：使用Zotero连接器编写API(/connector/*)，独立于插件。
  • zotero-local 以工具为导向； list_mcp_resources 工具完全工作时可能是空的。

故障排除

  • 写入工具失败/“本地API为只读”：安装配套插件并重新启动 佐特罗；确认 http://127.0.0.1:23119/zotero-write/version 回答。
  • MCP已加载但没有资源：预期--检查工具(health_check)相反。
  • PDF导入不起作用：保持Zotero开放；允许其他应用程序与Zotero通信； 确认 http://127.0.0.1:23119/connector/ping 返回“Zotero正在运行”。
  • 慢 find_claim_evidence：较低 maxPdfCandidates / pdfConcurrency；提高 MCP_MAX_PDF_MB 只有在需要的时候。

自然语言检索

ask_zotero_nl 接受一个句子，例如。 找2024年发表的有关冠层光氮分布的文献 它 提取年份限制，并将常见的中文域名扩展到英文搜索变体。

相关 MCP