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	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 キー不要）

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

ローカル Zotero 7（CLI または MCP、API キー不要）

ローカルで実行中の Zotero デスクトップアプリを検索する場合（全文 PDF 検索を含む）は、Web API ではなく CLI または MCP サーバーを使用してください。どちらも、ローカル API アクセスを有効にした Zotero 7 が必要です。references/cli.md と references/mcp.md を参照してください。