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。