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 を参照してください。

エージェントの作業手順

1. 環境を確認します。 調査の問い、データベース、期間、採用基準を確認します。
2. 入力内容を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 1つのデータベースで絞り込んだクエリを使って検索し、結果が関連しているか確認します。
4. 上記の手順と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 すべての参考文献について、解決可能な識別子を持つ実在のレコードから取得したことを確認し、件数と検索文字列を記録します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の点を明記します。

次のような場合	対応
API によるレート制限、またはエラーが発生した場合	待機して再試行する、バッチサイズを小さくする、またはデータベースを切り替え、未対応の範囲を報告します。
これらの手順にある関数、フラグ、エンドポイントがインストール済みのバージョンに存在しない場合	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、対応を調整してユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧な場合	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• 取得していない論文を決して要約しないでください。記憶を頼りに引用しないでください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有 GPU やクラウドのクォータを消費する操作、個人データや患者データに触れる操作、元に戻せない操作を行う前に、必ず確認してください。

関連スキル

• reference-manager-interop：Zotero、Mendeley、EndNote、JabRef、Paperpile、執筆ツール（LaTeX/BibTeX、Word、Google Docs、…
• citation-management：OpenAlex、PubMed、Google Scholar を検索し、CrossRef、PubMed、ar…を通じて DOI、PMID、PMCID、arXiv ID、URL からメタデータを抽出します
• literature-review：PubMed、arXiv、bioRxiv、Semantic Scholar を検索して（parallel-cli によるウェブ検索も併用）、系統的な文献レビューを実施し、スクリーニング…