
Zotero
- 231 installs
- 12 repo stars
- Updated February 12, 2026
- shoei05/claude-code-zotero-skill
Helps with ai & agent building tasks.
About
zotero is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.
- zotero
- AI & Agent Building
- AI-coding skill
Zotero by the numbers
- 231 all-time installs (skills.sh)
- +7 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #2,689 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/shoei05/claude-code-zotero-skill --skill zoteroAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 231 |
|---|---|
| repo stars | ★ 12 |
| Last updated | February 12, 2026 |
| Repository | shoei05/claude-code-zotero-skill ↗ |
What it does
Helps with ai & agent building tasks.
Files
Zotero API Skill
Zotero のローカル HTTP サーバー(localhost:23119)および REST API(api.zotero.org)経由で文献管理操作を行う。
前提条件
ローカル API(Zotero 起動中のみ)
Zotero が起動中で、以下の設定が有効であること:
- Zotero > 環境設定 > 詳細 > 「Allow other applications on this computer to communicate with Zotero」にチェック
接続確認:
curl -s http://localhost:23119/connector/pingREST API(クラウド操作)
環境変数が設定されていること:
ZOTERO_API_KEY: API キー(https://www.zotero.org/settings/keys で作成)ZOTERO_USER_ID: ユーザー ID
接続確認:
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" "https://api.zotero.org/keys/current"コマンド
1. DOI 一括インポート (/zotero import)
/zotero import <DOI1> <DOI2> ...
/zotero import --file <doi_list.txt>
/zotero import --collection "コレクション名"インポートスクリプト:
bash ~/.claude/skills/zotero/scripts/zotero_import.sh --dois "10.1038/xxx,10.2196/yyy" [--collection "名前"]処理フロー: 1. Zotero 起動確認(/connector/ping) 2. 対象コレクション特定(指定なければ現在選択中を使用) 3. 各 DOI → doi.org から BibTeX 取得(失敗時 CrossRef フォールバック) 4. /connector/import?session=<unique_id> に POST 5. 結果サマリー表示
2. 手動 BibTeX インポート (/zotero bibtex)
DOI のない文献用。BibTeX ファイルを直接インポート:
bash ~/.claude/skills/zotero/scripts/zotero_import.sh --bibtex /path/to/file.bibDOI 不明時は CrossRef API で検索:
curl -s "https://api.crossref.org/works?query.bibliographic=著者名+キーワード&rows=5"3. コレクション一覧 (/zotero collections)
curl -s http://localhost:23119/api/users/0/collections | python3 -c "
import json, sys
for c in json.load(sys.stdin):
d = c['data']
print(f\"{d['key']} {d['name']}\")"4. アイテム一覧 (/zotero list)
/zotero list # 現在選択中コレクション
/zotero list --collection "名前" # 指定コレクション5. アイテム検索 (/zotero search)
/zotero search "AI psychosis"REST API 操作
コレクション作成
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/collections" \
-d '[{"name": "コレクション名"}]'コレクション更新
curl -s -X PUT \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/collections/COLLECTION_KEY" \
-d '{"name": "新しい名前"}'アイテム作成(最大50件/リクエスト)
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items" \
-d '[{
"itemType": "journalArticle",
"title": "タイトル",
"creators": [{"creatorType": "author", "firstName": "名", "lastName": "姓"}],
"collections": ["COLLECTION_KEY"],
"tags": [{"tag": "タグ名"}]
}]'アイテム部分更新(PATCH)
curl -s -X PATCH \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY" \
-d '{"tags": [{"tag": "new-tag"}]}'アイテム削除
curl -s -X DELETE \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY"タグ一括削除
curl -s -X DELETE \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/tags?tag=tag1+||+tag2"グループライブラリ
すべてのエンドポイントは /users/<userID> を /groups/<groupID> に置き換えるだけ。
# 所属グループ一覧
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/groups"検索(REST API)
# キーワード検索
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items?q=keyword&qmode=titleCreatorYear"
# タグフィルタ(AND: 複数 tag、OR: || 区切り、NOT: - 接頭辞)
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items?tag=AI&tag=review"API 概要
ローカル API
| エンドポイント | メソッド | 用途 |
|---|---|---|
/connector/ping | GET/POST | 起動確認 |
/connector/import?session=ID | POST | BibTeX/RIS インポート |
/connector/getSelectedCollection | POST | 選択中コレクション |
/api/users/0/collections | GET | コレクション一覧 |
/api/users/0/collections/:key/items | GET | アイテム一覧 |
/api/users/0/items | GET | 全アイテム |
REST API (api.zotero.org)
| エンドポイント | メソッド | 用途 |
|---|---|---|
/users/<id>/collections | GET/POST | コレクション一覧/作成 |
/users/<id>/collections/<key> | PUT/DELETE | コレクション更新/削除 |
/users/<id>/items | GET/POST | アイテム一覧/作成(最大50件) |
/users/<id>/items/<key> | PUT/PATCH/DELETE | アイテム更新/削除 |
/users/<id>/tags | GET | タグ一覧 |
/users/<id>/tags?tag=... | DELETE | タグ一括削除 |
/users/<id>/searches | GET/POST | 保存済み検索 |
/users/<id>/items/<key>/file | GET/POST/PATCH | 添付ファイル |
/users/<id>/groups | GET | グループ一覧 |
/groups/<id>/... | 各種 | グループ操作 |
詳細: references/api-endpoints.md
重要な注意点
ローカル API
- Local API (`/api/...`) は GET のみ(読み取り専用)
- Connector API (`/connector/...`) は POST で読み書き可能
/connector/importのsessionパラメータは毎回ユニークにする(重複で 409 エラー)- BibTeX にシェル特殊文字がある場合は
--data-binary @file.bibでファイル経由送信 - インポート先は Zotero UI で選択中のコレクション に保存される
REST API
- 認証:
Zotero-API-Key: <key>ヘッダー(推奨) - 更新/削除時は
If-Unmodified-Since-Version: <version>が必須(未指定 → 428) - バッチ上限: 最大 50 件/リクエスト
- レートリミット:
Backoff/429 + Retry-Afterベース - 重複送信防止:
Zotero-Write-Token: <token>ヘッダー
.DS_Store
claude-code-zotero-skill
Claude Code から Zotero を直接操作するスキル — DOI 一括インポート、コレクション管理、キーワード・著者検索
macOS (Zotero 8.0.3) で動作確認済み。MCP サーバー不要。追加依存なし。curl だけで Zotero ローカル API を直接叩く軽量アプローチ。---
1. ローカル API だけでできること
Zotero が起動していれば、API キーの取得や外部アカウントの設定は一切不要で、以下のすべてが使えます。
できること一覧
| コマンド | 説明 |
|---|---|
/zotero import <DOIs> | DOI リストから BibTeX を自動取得して一括インポート |
/zotero import --file dois.txt | テキストファイルの DOI を一括インポート |
/zotero bibtex file.bib | BibTeX/RIS ファイルを直接インポート(DOI なし文献対応) |
/zotero collections | コレクション一覧を表示 |
/zotero list | 現在選択中コレクションのアイテム一覧 |
/zotero list --collection "名前" | 指定コレクションのアイテム一覧 |
/zotero search "keyword" | タイトル・著者名・年でキーワード検索 |
バッチ処理例: 19 件の DOI を含む参考文献リストを渡すと、DOI 自動抽出 → BibTeX 取得 → CrossRef フォールバック → 手動 BibTeX 生成 → 一括インポートまで自動実行。
セットアップ(これだけ)
1. Zotero 側の設定
1. Zotero を起動 2. Zotero > 環境設定 > 詳細 3. 「Allow other applications on this computer to communicate with Zotero」 にチェック 4. http://localhost:23119/api/ でアクセス可能になる
2. スキルを配置
git clone https://github.com/shoei05/claude-code-zotero-skill.git ~/.claude/skills/zotero3. 接続確認
curl -s http://localhost:23119/connector/ping
# => <html>Zotero is running</html>以上。追加のインストールは不要です。
動作環境
| 要件 | 詳細 |
|---|---|
| OS | macOS(動作確認済み) |
| Zotero | 7 / 8(ローカル API 有効化済み) |
| Claude Code | CLI 環境 |
| システム依存 | curl, python3, openssl(macOS 標準搭載・追加インストール不要) |
使い方
DOI 一括インポート
/zotero import 10.1038/s41746-023-00979-5, 10.2196/78238, 10.1016/j.compedu.2024.105224または DOI リストファイルから:
/zotero import --file ~/research/dois.txt処理フロー: 1. doi.org に BibTeX をリクエスト(Content Negotiation) 2. 失敗時は CrossRef API にフォールバック 3. Zotero Connector API (/connector/import) で現在選択中のコレクションに登録
手動 BibTeX インポート(DOI なし文献)
DOI がない文献(学会ガイドライン、ケースレポート等):
/zotero bibtex /path/to/manual.bibキーワード検索
/zotero search "AI psychosis"内部的には:
curl -s "http://localhost:23119/api/users/0/items?q=psychosis&qmode=titleCreatorYear"コレクション一覧・アイテム一覧
/zotero collections
/zotero list --collection "2602-生成AIとメンタルヘルス"ローカル API のアーキテクチャ
Zotero は localhost:23119 で 2 種類のローカル API を公開しています:
localhost:23119
├── /api/... ← Local API(GET のみ・読み取り専用)
│ ├── /users/0/collections
│ ├── /users/0/items
│ └── /users/0/items?q=keyword&qmode=titleCreatorYear
│
└── /connector/... ← Connector API(POST・読み書き可能)
├── /connector/ping
├── /connector/import?session=UNIQUE_ID
└── /connector/getSelectedCollection- Local API (`/api/...`) は GET のみ(読み取り専用)
- Connector API (`/connector/...`) は POST で読み書き可能
/connector/importのsessionパラメータは毎回ユニークにする(重複で 409 エラー)- インポート先は Zotero UI で選択中のコレクション に保存される
ユースケース(ローカル API)
DOI 一括インポート
/zotero import 10.1038/s41746-023-00979-5, 10.2196/78238
/zotero import --file ~/research/dois.txt --collection "My Review"dois.txt の形式:
# AI and Mental Health papers
10.1038/s41746-023-00979-5
10.2196/78238
https://doi.org/10.1016/j.compedu.2024.105224DOI 不明な文献の検索・登録
CrossRef API で検索 → DOI 特定 → インポート。見つからない場合は手動 BibTeX:
@article{Pierre2025,
title = {Case report title},
author = {Pierre, Joseph M. and Gaeta, Bryce},
journal = {Innovations in Clinical Neuroscience},
volume = {22}, pages = {11-13}, year = {2025}
}/zotero bibtex /tmp/paper.bibWeb ページ・ガイドラインの登録
@misc{APA2025,
title = {Health advisory on generative AI chatbots},
author = {{American Psychological Association}},
year = {2025},
url = {https://www.apa.org/topics/...},
note = {Retrieved 2026-02-11}
}系統的レビュー(Systematic Review)ワークフロー
1. 検索・DOI 収集: PubMed/Scholar → DOI リスト作成 2. 一括インポート: /zotero import --file dois.txt 3. スクリーニング: Zotero UI で include/exclude に分類 4. 確認: /zotero list --collection "SR - Include"
参考文献リストからの一括登録
論文の References セクションのテキストを Claude Code に渡すと: 1. DOI を自動抽出 2. DOI 不明分は CrossRef API で検索 3. 見つからない文献は手動 BibTeX 生成 4. 一括インポート実行
トラブルシューティング(ローカル API)
| 症状 | 原因 | 対処 |
|---|---|---|
Local API is not enabled | 環境設定未設定 | Zotero > 環境設定 > 詳細 > 通信許可にチェック |
SESSION_EXISTS (409) | セッション ID 重複 | 各リクエストにユニーク ID を付与(スクリプトは自動対応) |
| BibTeX 取得失敗 | DOI 未登録 or プレプリント | CrossRef API で正しい DOI を検索 |
400 on import | BibTeX パースエラー | --data-binary @file.bib でファイル経由送信 |
---
2. API キーを取得するとできること(REST API)
ローカル API だけでも日常的な文献管理は十分ですが、Zotero の API キーを取得すると、さらに以下のことが可能になります。
ローカル API ではできない、REST API で広がる機能
| 機能 | 説明 |
|---|---|
| コレクション作成 | CLI からコレクションを新規作成・名前変更・削除 |
| アイテムの直接作成 | JSON でアイテムを作成(BibTeX 経由ではなく直接、最大50件/リクエスト) |
| アイテムの更新・削除 | タイトル変更、タグ追加、メタデータ修正、アイテム削除 |
| タグの一括操作 | 不要タグの一括削除 |
| 添付ファイルアップロード | PDF 等をクラウドにアップロード |
| グループライブラリ | 共同研究グループの文献管理 |
| Zotero 未起動でも操作 | クラウド API なのでアプリ不要 |
| リモートからのアクセス | SSH 先やサーバーからでも操作可能 |
API キーの取得方法
1. https://www.zotero.org/settings/keys にアクセス 2. 「Create new private key」 をクリック 3. 設定:
- Key Description: 識別名(例:
claude-code-skill) - Allow library access: チェック
- Allow write access: チェック(コレクション作成・アイテム追加に必要)
- Default Group Permissions: グループを使う場合は
Read/Write
4. 「Save Key」 → API キーが生成される
同じページの上部に User ID も表示されます:
Your userID for use in API calls is XXXXXXX環境変数の設定
# ~/.zshrc や ~/.bashrc に追加
export ZOTERO_API_KEY="your_api_key_here"
export ZOTERO_USER_ID="your_user_id_here"source ~/.zshrc接続テスト
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/keys/current" | python3 -m json.toolREST API の使い方
認証
すべてのリクエストに API キーを付与:
-H "Zotero-API-Key: $ZOTERO_API_KEY" # 推奨
-H "Authorization: Bearer $ZOTERO_API_KEY" # 代替公開ライブラリの読み取りのみ認証不要。
コレクション作成
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/collections" \
-d '[{"name": "260212-文献チェック"}]'サブコレクション:
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/collections" \
-d '[{"name": "サブコレクション", "parentCollection": "PARENT_KEY"}]'アイテム作成
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items" \
-d '[{
"itemType": "journalArticle",
"title": "AI and Mental Health: A Systematic Review",
"creators": [{"creatorType": "author", "firstName": "John", "lastName": "Doe"}],
"date": "2025",
"DOI": "10.1234/example",
"collections": ["COLLECTION_KEY"],
"tags": [{"tag": "AI"}, {"tag": "mental-health"}]
}]'アイテム部分更新(タグ追加など)
curl -s -X PATCH \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY" \
-d '{"tags": [{"tag": "AI"}, {"tag": "reviewed"}]}'検索
# キーワード検索
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items?q=psychosis&qmode=titleCreatorYear"
# タグでフィルタ(AND: 複数 tag、OR: || 区切り、NOT: - 接頭辞)
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items?tag=AI&tag=mental-health"グループライブラリ
すべてのエンドポイントは /users/<userID> を /groups/<groupID> に置き換えるだけ:
# 所属グループ一覧
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/groups"
# グループのアイテム取得
curl -s -H "Zotero-API-Key: $ZOTERO_API_KEY" \
"https://api.zotero.org/groups/GROUP_ID/items"アイテム・コレクション削除
# 単体削除
curl -s -X DELETE \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items/ITEM_KEY"
# 複数削除(最大50件)
curl -s -X DELETE \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "If-Unmodified-Since-Version: $VERSION" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items?itemKey=KEY1,KEY2,KEY3"添付ファイルアップロード
3段階のフロー:
# 1. 添付アイテム作成
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/json" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items" \
-d '[{
"itemType": "attachment",
"parentItem": "PARENT_ITEM_KEY",
"linkMode": "imported_file",
"title": "paper.pdf",
"contentType": "application/pdf",
"filename": "paper.pdf"
}]'
# 2. アップロード認可取得
curl -s -X POST \
-H "Zotero-API-Key: $ZOTERO_API_KEY" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "If-None-Match: *" \
"https://api.zotero.org/users/$ZOTERO_USER_ID/items/ATTACHMENT_KEY/file" \
-d "md5=$(md5 -q paper.pdf)&filename=paper.pdf&filesize=$(stat -f%z paper.pdf)&mtime=$(stat -f%m paper.pdf)000"
# 3. 認可レスポンスの url にファイル本体を POST → upload 登録REST API の知っておくべきこと
バッチ制限
| 操作 | 上限 |
|---|---|
| 1リクエストでの作成/更新 | 最大 50 件 |
| 1リクエストでの複数削除 | 最大 50 件 |
ページング limit | 1-100(デフォルト 25) |
競合制御
更新・削除時はバージョン指定が必須:
-H "If-Unmodified-Since-Version: <version>"
# バージョン不一致 → 412 Precondition Failed
# バージョン未指定 → 428 Precondition Requiredレートリミット
固定の requests/sec 上限は非公開。以下のレスポンスに注意:
| レスポンス | 対処 |
|---|---|
Backoff: <seconds> ヘッダー | 指定秒数待つ |
429 Too Many Requests | Retry-After の秒数待つ |
503 Service Unavailable | Retry-After の秒数待つ |
トラブルシューティング(REST API)
| 症状 | 原因 | 対処 |
|---|---|---|
403 Forbidden | API キーの権限不足 | https://www.zotero.org/settings/keys で権限確認 |
412 Precondition Failed | バージョン競合 | 最新バージョンを取得してリトライ |
428 Precondition Required | バージョンヘッダー未指定 | 更新/削除時は If-Unmodified-Since-Version 必須 |
429 Too Many Requests | レート制限超過 | Retry-After ヘッダーの秒数待つ |
---
REST API エンドポイント一覧
詳細は references/api-endpoints.md を参照。
<prefix> = /users/<userID> または /groups/<groupID>
読み取り(GET)
| エンドポイント | 説明 |
|---|---|
<prefix>/collections | コレクション一覧 |
<prefix>/collections/top | トップレベルコレクション |
<prefix>/collections/<key> | 特定コレクション |
<prefix>/items | 全アイテム |
<prefix>/items/top | トップレベルアイテム |
<prefix>/items/<key> | 特定アイテム |
<prefix>/items/<key>/children | 子アイテム(添付/ノート) |
<prefix>/searches | 保存済み検索一覧 |
<prefix>/tags | タグ一覧 |
/users/<id>/groups | 所属グループ一覧 |
/keys/current | 現在の API キーの権限 |
書き込み(POST / PUT / PATCH / DELETE)
| エンドポイント | メソッド | 説明 |
|---|---|---|
<prefix>/items | POST | アイテム作成(最大50件) |
<prefix>/items/<key> | PUT / PATCH | アイテム更新 |
<prefix>/items/<key> | DELETE | アイテム削除 |
<prefix>/collections | POST | コレクション作成 |
<prefix>/collections/<key> | PUT / DELETE | コレクション更新/削除 |
<prefix>/searches | POST | 保存済み検索作成 |
<prefix>/tags?tag=... | DELETE | タグ一括削除 |
<prefix>/items/<key>/file | POST / PATCH | ファイルアップロード |
メタデータ(認証不要)
| エンドポイント | 説明 |
|---|---|
/itemTypes | アイテムタイプ一覧 |
/items/new?itemType=<type> | 新規アイテムテンプレート |
/itemTypeFields?itemType=<type> | タイプ別フィールド |
/schema | API スキーマ |
---
ZoteroMCP との違い
| 本スキル(直接 API) | ZoteroMCP | |
|---|---|---|
| 対象 | Claude Code(CLI) | Claude Desktop(GUI) |
| 依存関係 | なし(curl + python3 のみ) | Node.js + pip/uv でサーバーインストール |
| アーキテクチャ | Zotero HTTP API を直接 curl で呼ぶ | MCP サーバープロセスを常駐 |
| セットアップ | スキルフォルダを配置するだけ | pip install + JSON 設定ファイル編集 |
| 書き込み | Connector API + REST API | Local API or Web API 経由 |
| オフライン | 完全対応(DOI 取得以外) | ローカル API モードで対応 |
| バッチ処理 | DOI リスト一括インポートスクリプト付き | 個別操作 |
ファイル構成
~/.claude/skills/zotero/
├── SKILL.md # スキル定義(Claude Code が読み込む)
├── README.md # このファイル
├── scripts/
│ └── zotero_import.sh # DOI/BibTeX インポートスクリプト
└── references/
└── api-endpoints.md # API エンドポイント詳細リファレンス参考リンク
- Zotero Web API v3 公式ドキュメント: https://www.zotero.org/support/dev/web_api/v3/
- Basics — エンドポイント一覧、認証、検索パラメータ
- Write Requests — CRUD 操作、バッチ制限
- File Upload — 添付ファイルアップロード
- Full-Text Content — 全文インデックス
- Syncing — 同期プロトコル
- Streaming API — WebSocket リアルタイム通知
- API キー管理: https://www.zotero.org/settings/keys
ライセンス
MIT
Zotero API Endpoints Reference
1. ローカル API
Base URL: http://localhost:23119
Connector API(読み書き可能)
POST エンドポイント。Zotero Connector プロトコル。
POST /connector/ping
Zotero 起動確認。
curl -s http://localhost:23119/connector/ping
# => <html>Zotero is running</html>POST /connector/getSelectedCollection
Zotero UI で選択中のコレクション情報を取得。
curl -s -X POST http://localhost:23119/connector/getSelectedCollection \
-H "Content-Type: application/json" -d '{}'レスポンス: { "libraryID": 1, "name": "コレクション名", "id": 29, "targets": [...] }
POST /connector/import
BibTeX/RIS 等をインポート。Zotero UI で選択中のコレクションに保存。
curl -s -X POST "http://localhost:23119/connector/import?session=UNIQUE_ID" \
-H "Content-Type: application/x-bibtex" \
--data-binary @file.bibsession: 毎回ユニークな値(重複 → 409 SESSION_EXISTS)- 成功:
201 Created+ JSON(アイテム配列) - 対応: BibTeX, RIS, その他 Zotero translator 認識フォーマット
POST /connector/saveItems
ブラウザ拡張がメタデータ付きアイテムを保存する際に使用。
POST /connector/saveSnapshot
Web ページスナップショットの保存。
Local API(読み取り専用・GET のみ)
Zotero Web API v3 互換。
| エンドポイント | 説明 |
|---|---|
/api/users/0/collections | 全コレクション一覧 |
/api/users/0/collections/top | トップレベルのみ |
/api/users/0/collections/:key | 特定コレクション詳細 |
/api/users/0/collections/:key/collections | サブコレクション |
/api/users/0/collections/:key/items | コレクション内アイテム |
/api/users/0/items | 全アイテム |
/api/users/0/items/:key | 特定アイテム |
/api/users/0/items/top | 添付ファイル・ノート除外 |
/api/users/0/searches | 保存済み検索 |
/api/users/0/searches/:key/items | 検索結果アイテム |
/api/groups/:groupID/... | グループライブラリ |
---
2. REST API (Web API v3)
Base URL: https://api.zotero.org
認証
# 推奨
-H "Zotero-API-Key: <key>"
# 代替
-H "Authorization: Bearer <key>"
# 非推奨
?key=<key>API キー取得: https://www.zotero.org/settings/keys
プレフィックス
<prefix> = /users/<userID> または /groups/<groupID>
読み取りエンドポイント(GET)
コレクション
GET <prefix>/collections # コレクション一覧
GET <prefix>/collections/top # トップレベル
GET <prefix>/collections/<collectionKey> # 特定コレクション
GET <prefix>/collections/<collectionKey>/collections # サブコレクションアイテム
GET <prefix>/items # 全アイテム
GET <prefix>/items/top # トップレベル(添付除外)
GET <prefix>/items/trash # ゴミ箱
GET <prefix>/items/<itemKey> # 特定アイテム
GET <prefix>/items/<itemKey>/children # 子アイテム
GET <prefix>/publications/items # My Publications
GET <prefix>/collections/<collectionKey>/items # コレクション内
GET <prefix>/collections/<collectionKey>/items/top # コレクション内トップ保存済み検索
GET <prefix>/searches # 検索一覧
GET <prefix>/searches/<searchKey> # 特定検索タグ
GET <prefix>/tags # 全タグ
GET <prefix>/tags/<url+encoded+tag> # 特定タグ
GET <prefix>/items/<itemKey>/tags # アイテムのタグ
GET <prefix>/collections/<collectionKey>/tags # コレクションのタグ
GET <prefix>/items/tags # 全アイテムのタグ
GET <prefix>/items/top/tags # トップアイテムのタグ
GET <prefix>/items/trash/tags # ゴミ箱のタグ
GET <prefix>/collections/<key>/items/tags # コレクション内アイテムのタグ
GET <prefix>/collections/<key>/items/top/tags # コレクション内トップのタグ
GET <prefix>/publications/items/tags # Publications のタグユーザー・グループ
GET /users/<userID>/groups # 所属グループ一覧
GET /groups/<groupID> # グループ詳細
GET /keys/<key> # API キー情報
GET /keys/current # 現在のキー情報その他
GET <prefix>/deleted?since=<version> # 削除済み
GET <prefix>/fulltext?since=<version> # 全文インデックス更新
GET <prefix>/items/<itemKey>/fulltext # アイテム全文メタデータ(認証不要)
GET /schema # API スキーマ
GET /itemTypes # アイテムタイプ一覧
GET /itemFields # フィールド一覧
GET /itemTypeFields?itemType=<type> # タイプ別フィールド
GET /itemTypeCreatorTypes?itemType=<type> # タイプ別著者タイプ
GET /creatorFields # 著者フィールド
GET /items/new?itemType=<type> # 新規テンプレート
GET /items/new?itemType=attachment&linkMode=<mode> # 添付テンプレート書き込みエンドポイント
アイテム
POST <prefix>/items # 作成(最大50件)
PUT <prefix>/items/<itemKey> # 全体更新
PATCH <prefix>/items/<itemKey> # 部分更新
DELETE <prefix>/items/<itemKey> # 単体削除
DELETE <prefix>/items?itemKey=<k1>,<k2>,... # 複数削除(最大50件)コレクション
POST <prefix>/collections # 作成
PUT <prefix>/collections/<collectionKey> # 更新
DELETE <prefix>/collections/<collectionKey> # 単体削除
DELETE <prefix>/collections?collectionKey=<k1>,... # 複数削除(最大50件)保存済み検索
POST <prefix>/searches # 作成
DELETE <prefix>/searches?searchKey=<k1>,<k2>,... # 複数削除(最大50件)タグ
DELETE <prefix>/tags?tag=<tag1> || <tag2> # 一括削除(最大50件)全文テキスト
PUT <prefix>/items/<itemKey>/fulltext # 全文テキスト設定ファイルアップロード
GET <prefix>/items/<itemKey>/file # ファイル取得
POST <prefix>/items/<itemKey>/file # アップロード認可/登録
PATCH <prefix>/items/<itemKey>/file?algorithm=... # 差分アップロードキー管理
DELETE /keys/<key> # API キー削除検索クエリパラメータ
| パラメータ | 値 | 説明 |
|---|---|---|
q | 文字列 | 検索キーワード |
qmode | titleCreatorYear / everything | 検索範囲 |
itemType | タイプ名 | アイテムタイプフィルタ |
tag | タグ名 | タグフィルタ(AND: 複数指定、OR: `\ |
since | バージョン番号 | 指定バージョン以降の変更 |
itemKey | キー(カンマ区切り) | 特定アイテム取得(最大50) |
includeTrashed | 0 / 1 | ゴミ箱含む |
sort | フィールド名 | ソート基準 |
direction | asc / desc | ソート方向 |
start | 数値 | オフセット |
limit | 1-100 | 取得件数 |
format | json / atom / bib / keys / versions | 出力形式 |
レートリミット
Backoff: <seconds>— サーバー負荷時に付与(成功レスポンスにも)429 Too Many Requests+Retry-After: <seconds>— レート超過503 Service Unavailable+Retry-After: <seconds>— メンテナンス等- 固定の requests/sec 上限値は非公開
バッチ制限
- 作成/更新: 最大 50 件/リクエスト
- 複数削除: 最大 50 件/リクエスト
- ページング
limit: 1-100 format=keys/format=versions: 制限なし
競合制御
If-Unmodified-Since-Version: <version> # 更新・削除時必須
If-None-Match: * # 新規ファイルアップロード時
If-Match: <md5> # 既存ファイル更新時
Zotero-Write-Token: <token> # 重複送信防止(12時間キャッシュ)---
3. 外部 API
doi.org Content Negotiation(DOI → BibTeX)
curl -sL -H "Accept: application/x-bibtex" "https://doi.org/10.1038/s41746-023-00979-5"CrossRef API(文献検索)
curl -s "https://api.crossref.org/works?query.bibliographic=著者+タイトル&rows=5"
curl -s "https://api.crossref.org/works?query.bibliographic=検索語&filter=from-pub-date:2025-01-01&rows=5"レスポンス: message.items[].DOI から DOI を取得。
---
4. Streaming API
WebSocket 経由のリアルタイム通知。
wss://stream.zotero.orgライブラリの変更をリアルタイムで受信可能。詳細: https://www.zotero.org/support/dev/web_api/v3/streaming_api
#!/bin/bash
# zotero_import.sh - Zotero ローカル API 経由で文献をインポート
#
# Usage:
# zotero_import.sh --dois "10.1038/xxx,10.2196/yyy"
# zotero_import.sh --dois "10.1038/xxx" --collection "コレクション名"
# zotero_import.sh --file dois.txt
# zotero_import.sh --bibtex references.bib
set -euo pipefail
ZOTERO_URL="http://localhost:23119"
DOIS=""
DOI_FILE=""
BIBTEX_FILE=""
COLLECTION_NAME=""
while [[ $# -gt 0 ]]; do
case "$1" in
--dois) DOIS="$2"; shift 2 ;;
--file) DOI_FILE="$2"; shift 2 ;;
--bibtex) BIBTEX_FILE="$2"; shift 2 ;;
--collection) COLLECTION_NAME="$2"; shift 2 ;;
*) echo "Unknown option: $1"; exit 1 ;;
esac
done
# --- Check Zotero ---
PING=$(curl -s --max-time 5 "$ZOTERO_URL/connector/ping" 2>/dev/null || true)
if ! echo "$PING" | grep -q "Zotero"; then
echo "ERROR: Zotero is not running or local API is not enabled."
echo " 1. Launch Zotero"
echo " 2. Preferences > Advanced > Enable 'Allow other applications to communicate'"
exit 1
fi
echo "OK: Zotero is running"
# --- Show target collection ---
if [[ -n "$COLLECTION_NAME" ]]; then
echo "Note: Select '$COLLECTION_NAME' in Zotero UI before import."
fi
SELECTED=$(curl -s -X POST "$ZOTERO_URL/connector/getSelectedCollection" \
-H "Content-Type: application/json" -d '{}' 2>/dev/null)
CURRENT_NAME=$(echo "$SELECTED" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('name','(library root)'))" 2>/dev/null)
echo "Target collection: $CURRENT_NAME"
# --- BibTeX file import ---
if [[ -n "$BIBTEX_FILE" ]]; then
if [[ ! -f "$BIBTEX_FILE" ]]; then
echo "ERROR: File not found: $BIBTEX_FILE"; exit 1
fi
SESSION_ID="import-bib-$(date +%s)-$(openssl rand -hex 4)"
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
"$ZOTERO_URL/connector/import?session=$SESSION_ID" \
-H "Content-Type: application/x-bibtex" \
--data-binary "@$BIBTEX_FILE" 2>/dev/null)
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
if [[ "$HTTP_CODE" == "201" ]]; then
BODY=$(echo "$RESPONSE" | sed '$d')
COUNT=$(echo "$BODY" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo "?")
echo "SUCCESS: Imported $COUNT item(s) from $BIBTEX_FILE"
else
echo "FAIL: HTTP $HTTP_CODE"; echo "$RESPONSE" | sed '$d'
fi
exit 0
fi
# --- Build DOI list ---
DOI_LIST=()
if [[ -n "$DOIS" ]]; then
IFS=',' read -ra DOI_LIST <<< "$DOIS"
fi
if [[ -n "$DOI_FILE" ]]; then
[[ ! -f "$DOI_FILE" ]] && echo "ERROR: File not found: $DOI_FILE" && exit 1
while IFS= read -r line; do
[[ -z "$line" || "$line" == \#* ]] && continue
doi=$(echo "$line" | grep -oE '10\.[0-9]{4,}[^ ]*' | head -1)
[[ -n "$doi" ]] && DOI_LIST+=("$doi")
done < "$DOI_FILE"
fi
if [[ ${#DOI_LIST[@]} -eq 0 ]]; then
echo "ERROR: No DOIs specified. Use --dois, --file, or --bibtex"; exit 1
fi
echo "Processing ${#DOI_LIST[@]} DOI(s)..."
echo ""
SUCCESS=0; FAIL=0; FAILED_ITEMS=()
for doi in "${DOI_LIST[@]}"; do
doi=$(echo "$doi" | xargs)
echo "--- DOI: $doi ---"
BIBTEX=$(curl -sL --max-time 15 -H "Accept: application/x-bibtex" "https://doi.org/$doi" 2>/dev/null)
if [[ -z "$BIBTEX" ]] || echo "$BIBTEX" | grep -q "<!DOCTYPE\|Resource not found\|404\|DOI Not Found"; then
echo " doi.org failed, trying CrossRef..."
BIBTEX=$(curl -sL --max-time 15 -H "Accept: application/x-bibtex" "https://data.crossref.org/$doi" 2>/dev/null)
fi
if [[ -z "$BIBTEX" ]] || echo "$BIBTEX" | grep -q "<!DOCTYPE\|Resource not found\|404"; then
echo " FAIL: Could not fetch BibTeX"
FAIL=$((FAIL + 1)); FAILED_ITEMS+=("$doi"); continue
fi
echo " BibTeX: ${#BIBTEX} bytes"
TMPBIB=$(mktemp /tmp/zotero_bib_XXXXXX.bib)
echo "$BIBTEX" > "$TMPBIB"
SESSION_ID="import-$(date +%s)-$(openssl rand -hex 4)"
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
"$ZOTERO_URL/connector/import?session=$SESSION_ID" \
-H "Content-Type: application/x-bibtex" \
--data-binary "@$TMPBIB" 2>/dev/null)
rm -f "$TMPBIB"
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
if [[ "$HTTP_CODE" == "201" ]]; then
echo " SUCCESS"; SUCCESS=$((SUCCESS + 1))
else
BODY=$(echo "$RESPONSE" | sed '$d')
echo " FAIL: HTTP $HTTP_CODE - $BODY"
FAIL=$((FAIL + 1)); FAILED_ITEMS+=("$doi")
fi
sleep 0.5
done
echo ""
echo "=== Result ==="
echo "Success: $SUCCESS / ${#DOI_LIST[@]}"
echo "Failed: $FAIL"
if [[ ${#FAILED_ITEMS[@]} -gt 0 ]]; then
echo ""; echo "Failed DOIs:"
for item in "${FAILED_ITEMS[@]}"; do echo " - $item"; done
fi