ClaudecodeとZoteroライブラリとの読み書き連携を行う

Zotero連携スキル

ClaudecodeとZoteroライブラリとの読み書き連携を行う。コレクションの参照、アイテム検索、新規文献の追加が可能。

前提条件

Zoteroデスクトップアプリが起動していること
Local APIが有効であること（設定 → 詳細 → 「他のアプリケーションからZoteroのローカルAPIへのアクセスを許可する」）
Zoteroデータディレクトリ: /Users/xxxxx/Zotero/
ローカルAPIエンドポイント: http://localhost:23119

API仕様

読み取り（Local API — GET のみ対応）

# コレクション一覧
curl -s "http://localhost:23119/api/users/0/collections"

# 特定コレクション内のアイテム一覧
curl -s "http://localhost:23119/api/users/0/collections/{COLLECTION_KEY}/items"

# アイテム詳細
curl -s "http://localhost:23119/api/users/0/items/{ITEM_KEY}"

# アイテム検索（タイトル等）
curl -s "http://localhost:23119/api/users/0/items?q={SEARCH_QUERY}"

# ソート・フィルタ
curl -s "http://localhost:23119/api/users/0/items?sort=dateAdded&direction=desc&limit=25"

書き込み（Connector API — POST）

# アイテム追加（journalArticle の例）
curl -s -X POST "http://localhost:23119/connector/saveItems" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemType": "journalArticle",
        "title": "論文タイトル",
        "creators": [
          {"firstName": "太郎", "lastName": "山田", "creatorType": "author"}
        ],
        "date": "2024",
        "publicationTitle": "ジャーナル名",
        "volume": "1",
        "issue": "2",
        "pages": "100-110",
        "DOI": "10.xxxx/xxxxx",
        "url": "https://..."
      }
    ],
    "uri": "https://doi.org/10.xxxx/xxxxx",
    "cookie": {
      "libraryID": 1,
      "collectionID": COLLECTION_NUMERIC_ID
    }
  }'

注意: cookie.collectionID はコレクションの数値ID（APIキーではない）。
数値IDの取得方法:

curl -s "http://localhost:23119/connector/getSelectedCollection" \
  -H "Content-Type: application/json" -d '{}'
# → targets配列に "C2" のような形式で含まれる（数字部分を使用）

対応アイテムタイプ

journalArticle — 学術論文
conferencePaper — 会議論文
book / bookSection — 書籍・書籍章
thesis — 学位論文
report — テクニカルレポート
webpage — Webページ
preprint — プレプリント

削除

Local API経由での削除は未対応（Zotero 9.x時点）。手動削除が必要。

使い方

引数でサブコマンドを指定:

/zotero status — Zotero接続状態とLocal API有効性を確認
/zotero list [コレクション名] — コレクション内のアイテム一覧を表示
/zotero search [クエリ] — ライブラリ全体からアイテムを検索
/zotero add [コレクション名] — 指定コレクションにアイテムを追加（対話的に情報入力）
/zotero collections — 全コレクション一覧を表示
引数なし — status を実行

実行手順

status（接続確認）

curl -s "http://localhost:23119/api" でZotero起動確認
curl -s "http://localhost:23119/api/users/0/collections" でLocal API有効確認
失敗時は以下をガイド:
- Zotero未起動 → 「Zoteroを起動してください」
- Local API無効 → 設定手順を案内

list

コレクション名からキーを特定（/api/users/0/collections を取得し名前マッチ）
/api/users/0/collections/{KEY}/items でアイテム取得
attachment を除外し、タイトル・著者・年・アイテムタイプを表形式で表示

search

/api/users/0/items?q={QUERY} で検索
結果をフィルタリングして表形式で表示

add

ユーザーに書誌情報を確認（タイトル、著者、年、DOI等）
コレクション名から数値IDを取得（Connector API の getSelectedCollection を使用）
Connector API /connector/saveItems でPOST
追加確認のため再度コレクションを読み取り

collections

/api/users/0/collections を取得
parentCollection フィールドを使って階層表示

既知のコレクション（参考）

よく使われるコレクションの対応表:

コレクション名	APIキー	数値ID

他のコレクションの数値IDは getSelectedCollection の targets 配列から "C{数値}" 形式で取得可能。

トラブルシューティング

"No endpoint found" → Zoteroは起動しているがLocal APIが無効。設定から有効化する
接続拒否 → Zoteroが起動していない。open -a Zotero で起動
"database is locked" → SQLiteに直接アクセスしようとした場合に発生。必ずAPI経由でアクセスすること
Connector APIで空レスポンス → 正常（成功時はボディなしで返る）

ochilab/zotero-skill.md

Select an option

No results found