alterlab-pyzotero

Pyzotero

Pyzotero は Zotero API v3 用の Python ラッパーです（2026-09 時点の最新リリースは 1.15.x）。Zotero ライブラリをプログラムから管理するために使用します。アイテムやコレクションの読み取り、文献情報の作成と更新、添付ファイルのアップロード、タグの管理、引用文献のエクスポートができます。また、ローカルの Zotero ライブラリ向けのオプションの CLI と MCP サーバーも付属しています。

このスキルを使用する場面

• コードから Zotero ライブラリ内のアイテム、コレクション、タグの読み取り、検索、一括編集を行う
• テンプレートからアイテムを作成したり、PDF を添付したり、BibTeX／CSL-JSON／書式設定済みの参考文献一覧をエクスポートしたりする
• Zotero と同期する調査ワークフロー（ウェブライブラリまたはローカルのデスクトップアプリ）を自動化する
• ターミナルからローカルの Zotero ライブラリをスクリプトで操作する（pyzotero CLI）、または 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=...) として渡せるキーが発行されます。ローカル API キーは zotero.org の API キーとは別のものです。詳細については、references/authentication.md をご覧ください。

AlterLab Academic Skills スイートの一部です。