pyzotero

Pyzotero

Pyzotero 是 Zotero API v3 的 Python 封装。可用它以编程方式管理 Zotero 文库：读取条目和分类，创建和更新参考文献，上传附件，管理标签，以及导出引文。

当前上游版本： pyzotero 1.13.0（PyPI，2026 年 5 月）。文档：pyzotero.readthedocs.io。

身份验证设置

所需凭据 — 从 https://www.zotero.org/settings/keys 获取：

• 用户 ID：显示为“Your userID for use in API calls”
• API 密钥：在 https://www.zotero.org/settings/keys/new 创建
• 文库 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	面向大模型客户端的 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 密钥）

zot = Zotero(library_id='123456', library_type='user', local=True)
items = zot.items()

本地 Zotero 7（CLI 或 MCP，无需 API 密钥）

要搜索本地运行的 Zotero 桌面应用（包括 PDF 全文搜索），请使用 CLI 或 MCP 服务，而不是 Web API。两者都要求使用已启用本地 API 访问权限的 Zotero 7。请参阅 references/cli.md 和 references/mcp.md。

Agent 操作流程

1. 检查环境。 确认研究问题、数据库、日期范围和纳入标准。
2. 确定输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问，不要猜测。
3. 先运行小规模版本。 使用范围较窄的查询在一个数据库中运行搜索，并检查结果是否相关。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 每条参考文献都来自可检索到的真实记录，且具有可解析的标识符；记录数量和搜索字符串。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果出现以下情况	请执行以下操作
API 限流或返回错误	等待后重试、减小批次大小或切换数据库，并报告缺失情况。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），调整操作并告知用户。切勿虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 切勿总结尚未检索到的论文；切勿凭记忆引用论文。
• 将此处与版本相关的细节视为可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、消耗共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得同意。

相关技能

• reference-manager-interop：在 Zotero、Mendeley、EndNote、JabRef、Paperpile 和写作工具（LaTeX/BibTeX、Word、Google Docs、…）之间迁移和同步参考文献库
• citation-management：通过 CrossRef、PubMed 和 ar… 搜索 OpenAlex、PubMed 和 Google Scholar，并从 DOI、PMID、PMCID、arXiv ID 和 URL 提取元数据
• literature-review：通过搜索 PubMed、arXiv、bioRxiv 和 Semantic Scholar（以及通过 parallel-cli 进行网络搜索）开展系统性文献综述，筛选…