用途
pyzotero 是 Zotero API v3 的 Python 封装库,用于以编程方式管理 Zotero 文献库。它可以读取条目和分类、创建与更新参考文献、上传附件、管理标签,以及导出引文。当前上游版本为 pyzotero 1.13.0(PyPI,2026 年 5 月),官方文档位于 pyzotero.readthedocs.io。
认证设置
所需凭据可从 https://www.zotero.org/settings/keys 获取:
- User ID:页面中显示为 "Your userID for use in API calls"
- API Key:在 https://www.zotero.org/settings/keys/new 创建
- Library ID:群组库为群组 URL 中 /groups/ 之后的整数
凭据可存入环境变量或 .env 文件:
ZOTERO_LIBRARY_ID=your_user_id
ZOTERO_API_KEY=your_api_key
ZOTERO_LIBRARY_TYPE=user # or "group"
完整设置细节见 references/authentication.md。
安装
uv add pyzotero # Web API client
uv add "pyzotero[cli]" # + local CLI (Zotero 7)
uv add "pyzotero[mcp]" # + MCP server for LLM clients (Zotero 7)
快速开始
import os
from pyzotero import Zotero
zot = Zotero(
library_id=os.environ['ZOTERO_LIBRARY_ID'],
library_type=os.environ.get('ZOTERO_LIBRARY_TYPE', 'user'),
api_key=os.environ['ZOTERO_API_KEY'],
)
# Retrieve top-level items (returns 100 by default)
items = zot.top(limit=10)
for item in items:
print(item['data']['title'], item['data']['itemType'])
# Search by keyword
results = zot.items(q='machine learning', limit=20)
# Retrieve all items (use everything() for complete results)
all_items = zot.everything(zot.items())
核心概念
- 一个 Zotero 实例绑定单个文献库(用户库或群组库),所有方法都作用于该库。
- 条目数据位于 item['data'],可访问 item['data']['title']、item['data']['creators'] 等字段。
- pyzotero 默认返回 100 条(API 默认 25 条)。使用 zot.everything(zot.items()) 获取全部条目。
- 写入方法成功时返回 True,失败时抛出 ZoteroError。
参考文件
| 文件 | 内容 |
|---|---|
| references/authentication.md | 凭据、库类型、本地模式 |
| references/read-api.md | 获取条目、分类、标签、群组 |
| references/search-params.md | 过滤、排序、搜索参数 |
| references/write-api.md | 创建、更新、删除条目 |
| references/collections.md | 分类 CRUD 操作 |
| references/tags.md | 标签访问与管理 |
| references/files-attachments.md | 文件下载与附件上传 |
| references/exports.md | BibTeX、CSL-JSON、参考文献导出 |
| references/pagination.md | follow()、everything()、生成器 |
| references/full-text.md | 全文内容索引与访问 |
| references/saved-searches.md | 保存的搜索管理 |
| references/cli.md | 命令行界面(本地 Zotero 7) |
| references/mcp.md | 面向 LLM 客户端的 MCP 服务器(本地 Zotero 7) |
| references/error-handling.md | 错误与异常处理 |
常见模式
获取并修改条目:
item = zot.item('ITEMKEY')
item['data']['title'] = 'New Title'
zot.update_item(item)
从模板创建条目:
template = zot.item_template('journalArticle')
template['title'] = 'My Paper'
template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'}
zot.create_items([template])
导出为 BibTeX:
zot.add_parameters(format='bibtex')
bibtex = zot.top(limit=50)
# bibtex is a bibtexparser BibDatabase object
print(bibtex.entries)
本地模式(只读,无需 API Key):
zot = Zotero(library_id='123456', library_type='user', local=True)
items = zot.items()
本地 Zotero 7(CLI 或 MCP,无需 API Key)
如需搜索本地运行的 Zotero 桌面应用(包括 PDF 全文搜索),应使用 CLI 或 MCP 服务器而非 Web API。两者都要求 Zotero 7 并启用本地 API 访问。详见 references/cli.md 与 references/mcp.md。
智能体操作流程
- 检查环境:确认研究问题、数据库、日期范围和纳入标准。
- 明确输入:从数据或用户处确认格式、标识符和参数。对任何会改变结果的取值,应询问而非猜测。
- 先小规模运行:在单个数据库上用窄查询运行搜索,检查结果是否相关。
- 使用上述说明和参考文件执行完整任务。
- 验证结果:每条参考文献都来自具有可解析标识符的真实记录;记录计数和搜索字符串。
- 报告:说明运行了什么(版本、命令、参数)、检查了什么,以及仍不确定的内容。
异常处理:
| 情况 | 处理 |
|---|---|
| API 限流或返回错误 | 退避重试、减小批量大小或切换数据库,并报告缺口 |
| 说明中的函数、标志或端点在已安装版本中缺失 | 查阅已安装版本自身的文档(help()、--help、官方文档),调整后告知用户。绝不臆造 API |
| 必需输入、标识符或参数不明确 | 询问用户,或在运行前明确说明假设 |
完整性规则
- 绝不编造结果、参数、标识符、引文或统计数据。无法运行或验证的内容应如实说明。
- 绝不总结未获取的论文;绝不凭记忆引用。
- 此处版本相关细节可能已过时:请对照已安装版本的官方文档确认。
- 涉及花钱、消耗共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前,先征得同意。
相关技能
- reference-manager-interop:在 Zotero、Mendeley、EndNote、JabRef、Paperpile 与写作工具(LaTeX/BibTeX、Word、Google Docs 等)之间迁移和同步文献库。
- citation-management:搜索 OpenAlex、PubMed 和 Google Scholar,通过 CrossRef、PubMed 等从 DOI、PMID、PMCID、arXiv ID 和 URL 提取元数据。
- literature-review:通过搜索 PubMed、arXiv、bioRxiv 和 Semantic Scholar(以及通过 parallel-cli 进行网络搜索)执行系统性文献综述与筛选。