alterlab-pyzotero

Pyzotero

Pyzotero 是 Zotero API v3 的 Python 封装库（截至 2026-09，当前版本为 1.15.x）。可用它以编程方式管理 Zotero 文库：读取条目和分类、创建和更新参考文献、上传附件、管理标签以及导出引文。它还提供可选的 CLI 和用于本地 Zotero 文库的 MCP 服务。

何时使用此技能

• 通过代码读取、搜索或批量编辑 Zotero 文库中的条目、分类和标签
• 根据模板创建条目、附加 PDF，或导出 BibTeX / CSL-JSON / 格式化参考书目
• 自动化与 Zotero（网络文库或本地桌面应用）同步的研究工作流
• 通过终端（pyzotero CLI）编写脚本管理本地 Zotero 文库，或将其提供给 AI 客户端使用（MCP 服务）

不适用的场景

场景	请改用
在学术数据库中发现新论文	alterlab-research-lookup 或 alterlab-openalex
在没有 Zotero 文库的情况下将 DOI 转换为 BibTeX，或搜索 Google Scholar/PubMed	alterlab-citation-mgmt
检查参考书目中的条目是否真实存在 / 找出虚构的参考文献	alterlab-citation-verifier
根据 PDF 文件夹构建证据表	alterlab-pdf-extract

身份验证设置

所需凭据 — 从 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
# or with CLI support (local library search, writes, collection management):
uv add "pyzotero[cli]"
# or the MCP server (read-only unless started with --enable-writes):
uv add "pyzotero[mcp]"

快速入门

from pyzotero import Zotero

zot = Zotero(library_id='123456', library_type='user', api_key='ABC1234XYZ')

# 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，否则会引发 PyZoteroError 子类异常（来自 pyzotero.errors；所有类名均以 Error 结尾，例如 ResourceNotFoundError）。

参考文件

文件	内容
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	命令行界面用法
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)

本地模式（无需 Web API 密钥）

连接正在运行的 Zotero 桌面应用（Zotero 7+，并且已在“设置”>“高级”中启用“允许此计算机上的其他应用程序与 Zotero 通信”）。读取无需密钥：

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

只有 Zotero 10 或更高版本支持写入本地文库，且需要用户同意：zot.authorize_local("My script") 会让 Zotero 显示“允许 / 始终允许 / 拒绝”对话框。“允许”会生成一次性密钥；“始终允许”会生成一个密钥，你可以保存并通过 Zotero(..., local=True, local_api_key=...) 传回。Local API 密钥与 zotero.org API 密钥无关。详情请见：references/authentication.md。

AlterLab Academic Skills 套件的一部分。