使用说明
Zotero MCP服务器v3.5.1
本地第一个Zotero MCP服务器和CLI，用于管理真正的Zotero桌面 图书馆。v3.5.1支持语义工具边界，而不是强制合并：每个 该工具映射到一个Zotero对象或工作流，具有更清晰的参数。
这个工具是用来做什么的
| 目标 | 当前支持 |
|---|---|
| 检查一个Zotero项目 | 元数据、附件、PDF/MD/TXT清单、注释、注释 |
| 管理附件 | 导入存储的文件、链接本地文件、链接URL、更新或删除附件 |
| 管理可读文本 | 读/写/导入MD/TXT sidecar，读取Zotero文本索引，OCR PDF |
| 在本地编写 | 通过Zotero插件创建/更新/删除项目、笔记、附件、收藏和标签 |
| 组织库 | 收藏、项目转移、标记重命名/合并/删除、重复检查 |
| 诊断运行时 | 本地API、SQLite回退、本地桥接插件、库切换 |
建筑
AI client / CLI
|
v
src/index.ts, src/cli.ts
|
v
src/zotero-client.ts
|------------------------------|
v v
Zotero local API Zotero MCP Local Bridge plugin
127.0.0.1:23119/api 127.0.0.1:23119/mcp-bridge/*
read-only local data local CRUD via Zotero internal APIs
Zotero内置的本地API对读取是可靠的，但不实现项
CRUD写入。本项目船舶 zotero-local-bridge，Zotero桌面插件
这暴露了狭窄的本地写端点。不需要Zotero cloud API密钥，
并且不使用直接SQLite写入。
安装
npm install
npm run build
npm run plugin:pack
安装 dist-plugin/zotero-mcp-local-bridge.xpi 在Zotero桌面通过
Tools -> Add-ons -> Install Add-on From File....
验证：
curl -sS -H 'Zotero-Allowed-Request: 1' \
http://127.0.0.1:23119/mcp-bridge/ping
npm run dev:cli -- status
MCP工具
v3.5.1接口公开了11个语义工具。
| 工具 | 行动 | 目的 |
|---|---|---|
zotero_status |
check, libraries, switch_library |
诊断本地运行时并选择Zotero库 |
zotero_search |
筛选搜索 | 查找带有PDF/MD/TXT指示符的候选项 |
zotero_item |
单项读取 | 检查元数据、文件清单、笔记和注释 |
zotero_items |
create, update, delete, duplicates |
管理项目记录 |
zotero_import |
DOI参数或 file_path |
导入DOI元数据或本地文件，不进行元数据查找 |
zotero_attachments |
list, import, link_file, link_url, update, delete |
管理Zotero附件记录；本地文件显示标题默认为不带扩展名的文件名 |
zotero_texts |
list, read, write, import, ocr |
管理附件的MD/TXT/JSON文本表示 |
zotero_notes |
list, search, create, update, append, delete |
管理Zotero儿童笔记 |
zotero_collections |
list, items, create, rename, set_parent, delete, add_items, remove_items, transfer_items |
浏览和管理收藏 |
zotero_tags |
list, update_items, rename, merge, delete |
跨显式或匹配的项目管理标签 |
zotero_export |
BibTeX导出 | 导出引用 |
文件模型
Zotero项目通常包含一个或多个附件。PDF附件稍后可以 在同一Zotero存储目录中获取可读的sidecar文件：
| 文件类型 | 含义 |
|---|---|
| 原始附件文件 | |
| MD | Markdown提取或LLM可读文件 |
| TXT | 纯文本提取或可读回退 |
| 注意 | Zotero儿童笔记项目，与文件分开管理 |
使用 zotero_item 第一。它返回附件密钥以及是否为PDF、MD和TXT
文件存在。然后使用正确的特定对象工具：
| 需要 | 工具 |
|---|---|
| 添加/删除/链接附件记录 | zotero_attachments |
| 读取或创建MD/TXT侧车 | zotero_texts |
| 将PDF OCR为MD/TXT/JSON格式 | zotero_texts 随着 action=ocr |
| 创建或更新Zotero笔记 | zotero_notes |
CLI命令
CLI仍然可用于本地终端工作流：
search [query] Search with filters
item <key> Item details with file inventory
read-file <key> Read saved MD/TXT text
ocr <key> PaddleOCR conversion
add <dois...> DOI import with optional OA PDF download
duplicates Detect duplicate items
notes <query> Search notes
note <key> <content> Create child note
collections [key] Browse collections
tags List tags
tag <query> Batch tag update
export <keys...> Export BibTeX
libraries List/switch libraries
status System status check
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
ZOTERO_DATA_DIR |
否 | 覆盖自动检测到的Zotero数据目录 |
ZOTERO_FORCE_SQLITE |
否 | 设置 1 强制只读SQLite回退 |
ZOTERO_DISABLE_SQLITE_FALLBACK |
否 | 设置 1 失败而不是使用SQLite回退 |
PADDLEOCR_API_URL |
否 | 自定义PaddleOCR端点 |
PADDLEOCR_TOKEN |
否 | 自定义PaddleOCR身份验证令牌 |
UNPAYWALL_EMAIL |
否 | 在DOI导入期间，为Unpaywall礼貌池发送电子邮件 |
冒烟测试
npm run smoke:local-crud
烟雾测试通过MCP stdio在真实的Zotero Desktop实例上运行。它 验证11工具界面，创建临时集合、项目、注释， 导入和链接的附件、保存的MD sidecar文件、标签编辑和 收集转移。它通过Zotero的本地API验证结果 仅永久删除临时测试数据。
源布局
src/
├── index.ts MCP stdio entry point
├── server.ts semantic tool registration
├── cli.ts CLI entry point
├── zotero-client.ts Local API + bridge facade
├── local-bridge.ts HTTP client for /mcp-bridge endpoints
├── local-db.ts SQLite read-only metadata access
├── sql-fallback.ts SQLite read-only item queries
├── doi-import.ts CrossRef metadata + OA PDF lookup
├── paddle-ocr.ts PaddleOCR integration
└── tools/ MCP tool modules
zotero-local-bridge/
├── manifest.json Zotero plugin manifest
└── bootstrap.js Local CRUD endpoint implementation
许可证
麻省理工学院
