佐蒂
用于AI代理的轻量级Zotero MCP服务器。
它的作用
将AI代理连接到本地Zotero库的MCP服务器。提供8个工具：BM25对标题、摘要和索引附件全文进行排名搜索，项目内段落搜索，集合浏览，项目查找，BibTeX加上搜索返回的项目关键字的格式化引用导出，以及通过arXiv ID或DOI自动PDF附件进行论文摄取。
需求
- Python 3.10+
- Zotero桌面运行（默认目标为Zotero 8；也支持Zotero 7）
- Zotero本地API已启用：Zotero设置>高级>配置编辑器>设置
extensions.zotero.httpServer.localAPI.enabled到true - Zoty Bridge插件 已安装（用于PDF附件和收藏分配）
添加到您的代理
克劳德代码
从命令行添加：
claude mcp add zoty -- uvx zoty mcp添加到您的 .mcp.json 或 ~/.claude/settings.json:
{
"mcpServers": {
"zoty": {
"command": "uvx",
"args": ["zoty", "mcp"]
}
}
}法典
从命令行添加：
codex mcp add zoty -- uvx zoty mcp添加到您的 ~/.codex/config.toml:
[mcp_servers.zoty]
command = "uvx"
args = ["zoty", "mcp"]安装
需要 紫外线.
无需安装即可运行（建议用于MCP设置）：
uvx zoty mcp持久安装：
uv tool install zoty升级已安装的副本：
uv tool upgrade zoty如果你和佐蒂一起跑步 uvx 使用以下命令刷新到最新发布的版本，而不是安装它：
uvx --refresh zoty --version
uvx --refresh zoty doctor
uvx --refresh zoty setup从本地结账：
uv run zoty mcp
# Or install from source as a tool
uv tool install .Python包通过PyPI为用户提供CLI和MCP服务器。Zotero bridge插件在Python包内作为捆绑的XPI分发，并作为 GitHub发布资产；未来的桥梁更新将通过Zotero进行宣传 更新随每个版本发布的清单。
PDF阅读建议
为了在编码代理从zoty打开附件文件路径时获得最佳效果，请确保 poppler 并且相关的Poppler实用程序安装在机器上。在实践中，这通常意味着使用以下工具 pdftotext, pdfinfo，以及 pdftoppm 可在 PATH.
这对Claude Code尤为重要，它使用这些实用程序高效地阅读PDF页面。没有它们，代理可能仍然能够自己打开PDF文件，但页面提取往往更慢、更不可靠。
典型安装：
# macOS
brew install poppler
# Ubuntu / Debian
sudo apt-get install poppler-utilsZoty Bridge插件
一个小小的Zotero 7/8/9插件，让zoty在Zotero的特权上下文中执行JavaScript。这对于无法通过REST API的操作是必需的：PDF附件和集合分配都需要写入Zotero的SQLite数据库，该数据库会锁定外部进程。桥通过在Zotero内部运行JS来避开这个问题。
安装插件
- 找到捆绑的XPI，下载
zoty-bridge.xpi从 最新版本，或者自己构建：
uvx --refresh zoty setup --download-only uvx --refresh zoty setup make build- 在Zotero中：工具>插件，然后拖动
zoty-bridge.xpi进入插件窗口。 - 重新启动Zotero。
- 确认网桥正在运行：
uvx --refresh zoty doctorzoty setup 是一个有指导的、安全的默认流。它检查Zotero的本地API， 检查网桥端点，将您指向打包的XPI，然后告诉 下一个具体行动。 zoty setup --check 相当于没有 变化。先进的地方发展可以利用 zoty setup --install-profile但是 当Zotero运行时，该命令拒绝复制到Zotero配置文件中。
当前的网桥版本包括Zotero更新清单，因此安装此XPI后，Zotero可以检测到未来的网桥更新。
如果您升级到Zotero 9，并在Zotero 8上安装了一座旧桥，Zotero可能会显示该桥已禁用。安装最新版本 zoty-bridge.xpi 在插件窗口中，重新启动Zotero，如果Zotero在重新安装后将其禁用，则启用网桥。
仅用于本地开发，您还可以从命令行安装构建的XPI。请先退出Zotero，然后从存储库根目录运行以下命令：
ZOTERO_PROFILE="$(
python3 - <<'PY'
from configparser import ConfigParser
from pathlib import Path
root = Path.home() / "Library/Application Support/Zotero"
profiles = ConfigParser()
profiles.read(root / "profiles.ini")
for section in profiles.sections():
if section.startswith("Profile") and profiles.get(section, "Default", fallback="0") == "1":
path = Path(profiles.get(section, "Path"))
print(root / path if profiles.get(section, "IsRelative", fallback="1") == "1" else path)
break
else:
raise SystemExit("No default Zotero profile found")
PY
)"
mkdir -p "$ZOTERO_PROFILE/extensions"
cp zotero-plugin/dist/zoty-bridge.xpi "$ZOTERO_PROFILE/extensions/zoty-bridge@zoty.dev.xpi"网桥在上运行HTTP服务器 localhost:24119 当Zotero开放时。无需配置。
工具
| 工具 | 说明 |
|---|---|
search_library | 查找Zotero库中与关键字查询匹配的项目，按BM25对标题、摘要和索引附件全文进行排名，并提供可选的纯文本片段、附件计数、集合过滤、集合键/名称对和不区分大小写的项目类型值，如 journalArticle, preprint, conferencePaper, book, bookSection, thesis, report，以及 webpage |
search_within_item | 使用以下公式查找一个或多个已知项目中与关键字查询匹配的段落 search_library 结果钻入一篇特定的论文或比较几篇论文；顶级项目摘要包含父标题和每个匹配的父标题 key 仅在多项目排名中重复 |
list_collections | 列出所有包含关键字、名称和项目计数的集合 |
list_collection_items | 列出特定集合中的项目，包括每个项目上的集合键/名称对 |
get_item | 单个的完整元数据 item_key 或批量 item_keys；使用 key 场从 search_library, list_collection_items，或 get_recent_items 结果。单键请求保留详细的项目有效载荷，而批处理请求返回紧凑的项目记录 items 加上每项可选 errors |
get_bibtex_and_citation_for_items | BibTeX加上单个引文和参考书目文本的格式 item_key 或批量 item_keys；使用 key 场从 search_library, list_collection_items，或 get_recent_items 结果。两者可以结合使用，必须至少提供一个 |
get_recent_items | 最近添加的项目，按日期排序，每个项目上都有集合键/名称对 |
add_paper | 通过arXiv ID或DOI添加论文，自动下载PDF并防止收集范围内的重复 |
附件有效载荷包括 linkMode 作为描述性字符串(imported_file, imported_url, linked_file，或 linked_url)而不是Zotero的内部数字代码。
运作原理
读取操作仍在使用 皮佐特罗 对于集合/项API，但搜索现在在以下位置运行一个持久的sidecar索引 ~/.cache/zoty/fulltext-index.zoty从以下位置读取Zotero元数据 zotero.sqlite 在不可变模式下，重用Zotero提取的附件文本缓存(.zotero-ft-cache)对于PDF/EPUB/HTML全文，在本地对文本进行分块，并在后台重建不可变的BM25快照。启动时，zoty会同步加载活动快照（如果存在），然后在Zotero内容更改时排队刷新。
写入操作使用Zotero连接器端点(/connector/saveItems)以创建元数据项。PDF附件和集合分配通过zoty bridge插件，该插件在Zotero的特权上下文中执行JavaScript。同一个桥被用作瘦控制平面，要求Zotero在需要时生成缺失的全文缓存；zoty不会将插件拥有的表添加到 zotero.sqlite 或者通过网桥传输原始附件文本。这种双路径设计之所以存在，是因为Zotero的SQLite数据库使用了独占锁定——在Zotero运行时，外部进程可以读取它（不可变模式），但不能写入它。
arXiv流量在内部受到限制，以遵守arXiv的访问策略。并发 add_paper 调用队列透明：元数据请求以3秒的间隔序列化，arXiv PDF下载单独受到速率限制。
发展
make build # build zotero-plugin/dist/zoty-bridge.xpi and zoty-bridge-updates.json
make verify-build # rebuild plugin artifacts and fail if committed artifacts are stale
make test # run Python unit tests发布作者应遵循 发布.md桥XPI和Zotero更新清单是确定性构建输出，由CI检查。
在Zotero运行和zoty桥安装后，运行本地MCP烟雾测试：
uv run scripts/smoke_mcp.py烟雾测试故意不属于 make test 因为这取决于 当地Zotero简介和图书馆内容。请参阅脚本docstring 锁定项目/集合键或仅选择复制的环境变量 add_paper 测试。
许可证
麻省理工学院
跨会话的速率限制
zoty速率限制了正在运行的MCP服务器进程内的arXiv流量。如果几个 add_paper 调用一次到达同一台服务器，zoty将它们排队，并以arXiv安全的速度排出元数据请求。
该限制器不会在单独的zoty进程之间共享。如果您在每个代理、会话或编辑器窗口中启动一个zoty实例，则每个进程都将强制执行自己的限制，并且组合请求率仍可能超过arXiv策略。
如果您希望多个会话同时提取论文，请启动一个长期运行的zoty服务器，并将所有客户端指向同一实例。
启动一个共享本地服务器：
zoty mcp --transport streamable-http --host 127.0.0.1 --port 8000共享MCP端点将是：
http://127.0.0.1:8000/mcp如果需要其他端点路径：
zoty mcp \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000 \
--streamable-http-path /zoty-mcp然后将每个客户端指向相同的URL：
http://127.0.0.1:8000/zoty-mcp对于通过URL支持远程MCP服务器的客户端，配置应该如下所示：
{
"mcpServers": {
"zoty": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}当多个会话可能并行导入论文时，请避免这种模式，因为它会为每个客户端启动一个单独的zoty进程：
{
"mcpServers": {
"zoty": {
"command": "zoty",
"args": ["mcp"]
}
}
}推荐的启动顺序：
- 启动Zotero并确保Zotero连接器和
zoty-bridge插件可用。 - 启动一个共享zoty服务器
zoty mcp --transport streamable-http. - 配置每个代理或MCP客户端以连接到该现有服务器URL，而不是启动其自己的副本。
- 让共享服务器为每个人序列化arXiv元数据查找和速率限制arXiv PDF下载。
这使代理端的行为保持简单：工具调用在负载下可能需要更长的时间，但它们会自然排队，而不是敲打 export.arxiv.org.