Zotero Connector MCP

配套技能：zotero-literature-import。本仓库为独立 MCP 组件，采用 AGPL-3.0。

通过本机 MCP 调用浏览器中的真实 Zotero Connector，自动连接当前论文页，并核对 PDF 附件是否落盘。

安装

使用预构建插件

从 Releases 下载 zotero-connector-bridge-*.zip。此包已移除本机配对配置，不能直接复用发布者的授权。

1. 下载并解压同一版本的 MCP 源码，安装 Python 依赖：python -m venv .venv，再执行 .venv\Scripts\python.exe -m pip install -r requirements.txt。

2. 将插件包解压到该 MCP 源码目录中的 connector-ready，确认 manifest.json 直接位于其中。

3. 在 MCP 源码目录执行 python prepare.py provision --output connector-ready，自动生成自己的本机配对配置。

4. 浏览器“加载解压扩展”选择 connector-ready，注册并启动同一源码目录的 MCP 服务，再打开 Zotero 和论文页。

无需构建上游，也不需要填写令牌或保留桥接标签页。若下载了校验文件，可通过 Get-FileHash <插件包路径> -Algorithm SHA256 核对 SHA256SUMS.txt。插件请求的常规 Connector 权限及桥接新增的下载、后台连接能力仍由浏览器显示确认。

从源码构建

以下命令在本目录执行。需要 Python、Git、Node.js/npm 和支持本地解压扩展的 Chromium 116+ 浏览器。Windows 已完成实际部署验证。

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
git clone https://github.com/zotero/zotero-connectors.git connector-build
git -C connector-build checkout 876e41ad15139077f2e07b2f71a0fa94742e0b4a
git -C connector-build submodule update --init
npm --prefix connector-build ci --ignore-scripts
python build_windows.py
python prepare.py patch --source connector-build/build/manifestv3 --output connector-ready
python verify_build.py

build_windows.py 使用固定上游版本的资源和官方 Gulp 变换。输出目录已存在时拒绝覆盖；再次构建请先保留需要的内容并选择干净的构建目录。其他平台可按 上游构建说明生成未压缩 MV3 构建，再用 prepare.py patch 生成独立副本。找不到准确的官方工具栏钩子时，补丁会拒绝执行。

1. 在目标浏览器中加载 connector-ready 解压扩展，名称为 Zotero Connector (MCP Bridge)。避免同时启用原版和桥接版而重复保存。

2. 在 MCP 客户端注册 server.py，解释器使用上述虚拟环境中的 Python。参考 配置示例，替换为实际绝对路径。

3. 打开 Zotero，启用允许其他本机应用通信的设置。

4. 打开准确论文详情页并确认机构登录，调用 connector_status 或 save_and_check_pdf。

补丁自动生成 .bridge-token 和扩展内的 mcp-private-config.json。配对令牌与 Zotero 本机写入 key 是两种独立凭据；不要上传已经配对的扩展目录。后台连接不需要可见桥接页，也不用输入令牌。

MCP 使用 stdio，浏览器后台通过 127.0.0.1:23130 WebSocket 连接。环境变量 ZOTERO_MCP_WS_PORT 控制服务端监听端口，扩展配对端口必须与之相同；通常保留默认值。同一时间只启动一个实例，诊断客户端与正式服务不能争用端口。

Related MCP server: browser-mcp

工具

save_and_check_pdf 返回父条目、附件 key、页数、字节、MD5 和首页片段。校验格式与哈希不等于确定文献身份，仍需核对题名、作者和版本。DOI 不一致时保留候选并标记待审，不自动当作同文献合并。返回待下载或超时后先核对副作用，不能直接重复保存。

知网与 EBSCO

同一平台有效机构会话可连续复用。知网优先论文详情页；EBSCO 从用户所属机构入口搜索，准确匹配题名、作者、年份后进入 /search/details/，由 EBSCO Discovery Layer 翻译器保存。

缺 PDF 才走正常页面下载。EBSCO 可进入页面明确显示的 /viewer/pdf/ 阅读器，选择“下载 → 全文 → PDF → 下载”。阅读器 URL 是 HTML；成功提示不代替实际文件核验。EBSCO 可能提供 JSTOR DOI，不能不经核对就覆盖原有出版社 DOI。

一次持续授权（Windows）

python local_api.py status
python local_api.py authorize

用户在 Zotero 中选择“始终允许”后，本客户端将 remember:true 的新授权保存到当前 Windows 用户的凭据管理器，按 Zotero 数据库实例隔离。客户端复用自己的固定凭据项，不读取其他应用凭据。普通“允许”只有一次写请求权限，多阶段操作会在写入前停止。

local_api.py 是供本机代码使用的客户端；本 MCP 没有公开任意 API 写入、上传或归并工具。持续授权不扩大用户原有任务范围。401 后清除本客户端失效缓存并停止；不重放结果不明的写入。

python local_api.py forget 只移除本客户端缓存。撤销服务端许可需在 Zotero 设置 → 高级 → “清除写入授权”操作。status 的缓存存在标记不证明服务端尚未撤销：本机 GET 不校验写入 key。

验证

.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py" -v
node --test tests/test_extension.cjs
.\.venv\Scripts\python.exe tests/mcp_v2_smoke.py

集成测试使用真实 stdio MCP、WebSocket 和生产桥接脚本，浏览器 API 使用模拟宿主。JavaScript/集成测试依赖上游 connector-build/node_modules，需先完成安装步骤。Windows 凭据管理器测试仅使用随机虚构凭据项并清理；受限沙盒可能拒绝访问系统凭据库，需在当前用户的正常终端执行。

历史真实验证包括无桥接页连接、活动论文定位、知网及 EBSCO 保存、部分自动 PDF、重启自动恢复，以及持续许可下多阶段本机写入。它们不保证每篇论文或每个浏览器宿主都自动下载成功。

本机服务只绑定 loopback，拒绝非扩展来源和错误配对；活动页有歧义时拒绝写入；未知结果不自动重试。下载路径限定为明确链接，默认支持同源或知网域名族。请勿把本机端口转发或暴露到公网。

插件补全文与去重

EBSCO 正常下载未找到文件，不代表 Connector 也不能自动取得附件。用户手动插件导入成功后先查实际文件；首次只有元数据时，在用户明确要求重试或页面阻碍已解决后可有界重试一次插件，前后检查副作用，避免盲目重复。手动触发的成功须如实标记来源。

去重由调用方按用户授权执行：可以保留新抓取且有核验 PDF 的记录，先归并原笔记、附件、分类、标签及关系，再把旧记录软删除。MCP 不自动合并或删除，不把回收站中的全文计为活动分类完成。