zotio

Zoteroのための信頼と自動化のレイヤー

ドキュメント： はじめる · コマンド · MCP サーバー · 安全な書き込み · ワークフロー

zotioは、人間、スクリプト、MCP エージェントに、Zotero ライブラリ向けのローカル優先の検索と監査、プレビュー優先の書き込み、出所情報を付与した制約付きコンテキストを提供します。

まずは手早く確認： zotioをご自身のデータで試す前に、同梱ライブラリをチェックしてください。

brew install orgmentem/tap/zotio        # or grab a signed binary from Releases
zotio demo                              # bundled library: 34 classic papers, one genuinely retracted
ZOTIO_DEMO=1 zotio --data-source local items retract-check  # check every DOI against Retraction Watch data

KEY         STATUS      TYPE        NOTICE DOI                     DATE        SOURCE            TITLE
WAKEFLD98   correction  correction  10.1016/s0140-6736(04)15715-2  2004-03-06  retraction-watch  Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci...
WAKEFLD98   retracted   retraction  10.1016/s0140-6736(10)60175-4  2010-02-06  retraction-watch  Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci...
FAIR002016  correction  addendum    10.1038/s41597-019-0009-6      2019-03-19  publisher         The FAIR Guiding Principles for Scientific Da...
Checked 21 DOI-bearing items; 3 update notices flagged; 2 DOI(s) not registered with CrossRef.

これは、Zoteroをインストールせず、APIキーも使わずに、同梱ライブラリで撤回されたWakefieldの1998年MMR論文を検出した結果です（このチェックではCrossrefにライブで問い合わせます）。 zotio demo --resetはデモライブラリを削除して再作成し、元の状態に戻します。削除するには、デモレポートにdb_pathとして表示されるパスにあるdemo.dbファイルを削除してください。

Zotero自体も、同じRetraction Watchのデータを基に、撤回されたアイテムを開くと赤色で警告します。zotioはデスクトップアプリにない機能を追加します。訂正と懸念表明、スクリプトで利用できるライブラリ全体のレポート、そしてCIで失敗させられる終了コードです。

実際のライブラリを指定するには：

zotio init                                         # guided setup: detect Zotero, key, first sync, health check
zotio items retract-check                          # the same check, against your real library
zotio library health --for citation --fail-on high # fit to cite? (exit 11 if not)
zotio items bibcheck thesis.tex --fail-on-unknown  # every \cite{} resolves? (exit 11 if not)

zotio が選ばれる理由

Zotero の GUI は、読むことや引用することには優れています。しかし、大量の文献を対象に操作する必要が生じた途端に、使いにくくなります。PDF のない記事をすべて見つける、投稿前に重複した \cite{} キーを検出する、1週間分のハイライトをエクスポートする、Obsidian の保管庫を同期する、あるいは AI エージェントに信頼できるコンテキストを渡す、といった作業です。既存の CLI や pyzotero では生の API にアクセスできますが、その後は自分で連携処理を書き、リスクも自分で負うことになります。

zotio は、次の特長を備えた連携処理を提供します。

• 読み取りはローカルで行います。 実行中のデスクトップアプリを zotio に指定すれば、API キーもクラウドとの往復通信も不要です。また、同期済みのミラーを使ってオフラインでも動作します。
• 書き込みはプレビュー優先です。 変更を加える前に、すべての操作で実行計画を表示します。ゲートによって影響範囲を制限し、取り消せない操作には明示的なオプトインを求めます。追記専用ジャーナルを使って、取り消し可能な操作を元に戻せます。
• コンテキストには上限があり、出典情報が付与されます。 すべての結果に出典と鮮度が示されるため、人間やエージェントは情報を信頼できるか判断できます。zotio は LLM を呼び出しません。コンテキストを組み立てて予算を割り当てたうえで、モデルに渡します。

GUI での手作業が増えてきたときに使うツールです。後の工程で問題になるものを見つけ、安全に修正し、確認しながら取り込み、エージェントに信頼できるインターフェースを提供します。

仕組み

読み取りは常にお使いのマシン上で行います。書き込み先は操作の種類によって異なります。新しいアイテム（添付ファイル／PDF を含む）の作成には、ローカルデスクトップコネクターを優先して使用します（localhost:23119、キー不要。「Zotero に保存」ブラウザーボタンと同じ経路です）。一方、フィールドの編集、削除、情報の補完、タグ操作、移動、collections の作成／更新は Zotero Web API にルーティングされ、設定済みのキーが必要です。コネクター経由は優先設定です。--via auto は、デスクトップアプリが起動している個人用ライブラリでのみコネクターを使用し、それ以外の場合は Web API にフォールバックします（グループライブラリは常にクラウドに接続します）。既存のアイテムに対する attachments add で --via connector を指定すると、デスクトップ経由で明示的に操作できますが、ファイルを指定先へ移動するには Web API キーも必要です。書き込みはプレビュー優先です。アイテムの更新時には、適用時に Web 書き込み先からバージョンを読み取ります。適用された変更のうち対応するものは、既存のローカルミラーも更新するため、次回の読み取りでは再同期せずに変更を確認できます。

いつでも zotio doctor を実行すると、接続状況、キャッシュの鮮度、書き戻しが可能か読み取り専用かを示す writes: 行を確認できます。

主要機能：library health

6つの個別監査に代わり、「このライブラリは、次に行おうとしていることに適していますか？」という実際の問いに、1つのコマンドで答えます。

library health は、既存のチェック（citekey の競合、重複、メタデータの欠落、タグの不整合、添付ファイルの破損）を組み合わせ、重要度順に並べ、検出内容ごとに分類した1つのレポートを作成します。--for で「準備完了」の基準を指定します。

$ zotio library health --for quick
Health: needs attention
Scope: library · 846 top-level items (2103 mirrored rows) · source local · synced 1d ago · preset quick

High (13)
  [duplicate_candidates] doi="10.1002/bdm.2118" (2 items)
  [duplicate_candidates] title="Social psychology" (3 items)
  ... 11 more

Skipped (precondition unmet)
  broken_attachment_file — live check (needs Zotero desktop running); off by default.
    Fix: zotio library health --for quick --verify-files

Remediation plan (preview-first)
  duplicate_candidates — zotio items duplicates resolve --doi (preview first; add --yes after review)

ゲートとして適している理由は、次の3つです。

• CI をゲートできます。 --fail-on critical|high|info|any|none は、基準を満たさない場合に 11 で終了します。提出前のフックに追加できます。--require-fresh 24h は、ローカルミラーが古い場合に 12 で終了します。
• チェックできなかった項目も報告します。 デスクトップアプリが必要なチェック（添付ファイルの破損）は、対処方法を示す明確なスキップになります。そのスキップがゲートに関係する場合、実行は成功扱いにならず、セットアップが必要であることを示す 9 で終了します。
• 問題を修正するコマンドを示します。 検出結果には、既存の正確なコマンド（items enrich、items duplicates resolve、tags audit fix）を示す recommended_action が含まれます。library health は問題を報告し、指定されたコマンドが修正します。

参考文献リストの CI

--badge を使うと、健全性チェックの実行結果を shields.io endpoint の JSON アーティファクトとして出力できます。healthy は緑、検出ありは黄色、ゲート失敗は赤、「セットアップが必要」はオレンジで表示されます。

# .github/workflows/bibliography.yml (excerpt)
- run: zotio sync
- run: zotio library health --for citation --fail-on high --badge > badge.json
  # exit 11 fails the job when the bar isn't met; badge.json says why
# publish badge.json anywhere shields can reach (gh-pages, gist, artifact host), then:
#   https://img.shields.io/endpoint?url=https://<you>.github.io/<repo>/badge.json

論文やレビューのリポジトリに、bibliography | healthy のライブバッジを表示できます。citekey の競合や重複が1つでも入り込むと、ビルドが失敗します。--check-retractions を追加すると、ゲートで撤回された論文（Crossref の Retraction Watch データ）も確認できます。また、zotio items bibcheck paper.tex --fail-on-unknown で論文原稿自体にもゲートを設定できます。zotio-action を使えば、インストール、同期、ゲート、ベースラインとの差分確認まで実行でき、新しい問題が発生した場合にのみ失敗します（ガイド）。

実際の動作例をご覧ください。zotio のドキュメントデプロイでは、メンテナーが実際に使用している Zotero ライブラリをもとに、ライブバッジを公開しています（ワークフロー、ガイド）。

デフォルトで安全：書き込みエンジン

変更エンベロープ形式の書き込み（items enrich、tags audit fix、items duplicates resolve、items preprint-check fix、items create/update/move/delete/add-to-collection、collections create/update/delete/move、および import apply）は、共通の計画および結果形式を使用します。

• デフォルトではプレビューです。 変更を一切加えずに、計画／結果エンベロープが返されます。--yes で適用し、--dry-run が常に優先されます。
• プレビューは適用時の動作を予測します。 --yes と同じ読み取りを実行し、同じゲート（--max-changes、--allow-destructive、ローカル入力チェック）を評価します。適用時に拒否されるプレビューは、ok:false と error:{code,message} を出力し、適用時と同じコードで終了します。破壊的なプレビューで ok:true になるのは、--allow-destructive を指定した場合のみです。プレビューと適用のどちらでも、競合があると終了コード 1 で終了します。
• --dry-run は一切書き込みません。 Zotero への書き込み、ローカルファイルや .lock の兄弟ファイルの作成、設定の保存、ミラーへの書き戻しは行われません。読み取りは実行され、--deliver は引き続きコマンドの出力をルーティングします。sync、watch、init はプレビューできず、--dry-run を指定すると終了コード 2 で拒否されます。
• --agent を指定しても自動適用されません。 エージェントモードでは JSON および非対話型のデフォルトが設定されますが、書き込みには引き続き明示的な --yes が必要です。
• ゲートで影響範囲を制限します。 --max-changes のデフォルトは 500（--agent 指定時は 50）です。不可逆操作（マージ、完全削除、コレクション削除、creators rename、creators audit fix、vault resolve --keep-vault|--keep-remote）は、--allow-destructive がないと実行を拒否します。
• 書き込み後の読み取り。 対応する変更エンベロープ形式の書き込みは、適用時に既存のローカルミラーを更新します。後続のミラー読み取りでは、別途 sync を実行しなくても変更を確認できます。
• ジャーナルに記録され、元に戻せます。 適用された変更エンベロープ形式の各実行は、追記専用で記録されます（journal list／journal show）。journal undo <run-id> は元に戻せる操作（タグ名の変更、コレクションのメンバーシップ、items enrich による DOI／要約／引用フィールド／タグの書き込み――Extra から出典情報の行も取り除かれます――および作成操作。作成操作は作成したアイテムをゴミ箱に移動することで取り消されます。items delete によるゴミ箱への移動と items restore の実行は、反対の切り替え操作で元に戻されます）を取り消します。それ以外（マージ、完全削除、その他のフィールドの上書き）は推測で処理せず、明確に拒否します。Vault への書き込みも同じ --yes 承認ゲートを使用しますが、ノートごとの個別レポートを出力し、ジャーナルには記録されません。
• ローカル状態を扱うコマンド。 ローカル状態を破棄するコマンドは、デフォルトでプレビューし、--yes で適用します：auth logout と profile delete。ローカル状態を新規作成するだけのコマンドは、そのまま適用されます：auth set-token と profile save。

混乱を招かずにインポートする

レビュー用のチェックポイントを通じて、参考文献を一括インポートします。import apply は、マニフェストを確認し、必要に応じて編集した後にのみ書き込みます。

zotio import scan ~/Downloads/papers          # read-only: triage new vs duplicate vs attach-candidate
zotio import resolve ~/Downloads/papers > manifest.json   # resolve DOIs → editable manifest
#   ... review and edit manifest.json ...
zotio import apply manifest.json --dry-run     # preview the writes
zotio import apply manifest.json --yes         # schema-valid creation via the Web API

• スキャンでは、PDF のファイル名または PDF のバイト列から DOI を抽出し、フォルダー内の PDF を既存のライブラリと照合します。これにより、すでに登録済みのアイテムを再インポートせずに済みます。
• 解決では、結果を編集可能な JSON マニフェストに変換し、作成するエントリーの情報を CrossRef から補完します。ここが人による確認のポイントです。
• 適用では、明示的な --attach-mode none|linked-file|stored の指定に従い、スキーマに準拠したアイテムをプレビュー優先で作成します。stored はファイルのバイト列をアップロードします。--via connector を指定すると、1 回のセッションでアイテムとそのファイルを Zotero デスクトップに渡します。直接 Web API を使う経路にはファイルストレージの事前条件が適用され、上書きするには --allow-zotero-cloud が必要です。

resolve は DOI からメタデータを取得します（CrossRef を使用し、プレプリント PDF には arXiv から DOI へのルックアップを使用します）。PMID や ISBN は解決しません。これらの識別子を直接指定できる単発インポーターは import doi|pmid|arxiv|isbn|url|file|pdf です。保存先のコレクションキーは --to で指定します。

競合に安全な vault の双方向同期

Obsidian または Logseq の vault を、Zotero と双方向に同期します。自分の文章が上書きされることはありません。

zotio vault sync              # preview: shows the notes it would write
zotio vault sync --yes        # Zotero → one Markdown note per item (idempotent)
zotio vault push --dry-run    # your ## Notes region → a managed Zotero child note
zotio vault pull --dry-run    # remote note edits → your ## Notes region (fast-forward only)

各ノートには管理対象領域（frontmatter と、同期のたびに更新されるタイトル、要約、注釈の fenced ブロック）と、自分の領域（そのまま保持される ## Notes と文章）があります。書き戻しはファストフォワードのみです。両側で変更があった場合、zotio が内容をむやみにマージすることはありません。代わりに、_vault-zotero-conflicts/ に確認可能な競合アーティファクトを書き出して報告するため、差異を意図的に解決できます（vault resolve --keep-vault | --keep-remote | --recreate）。上書きが黙って行われることはありません。プッシュの前に vault audit を実行すると、読み取り専用の事前チェックを行えます。

~/.config/zotio/config.toml で vault を一度設定してください（--vault フラグで設定を上書きできます）。

[vault]
root = "~/Vaults/dev"    # ~ is expanded; base output dir
notes_dir = "Zotero"     # notes land in <root>/<notes_dir>
format = "obsidian"      # or "logseq"

GUI や pyzotero ではできないこと

ライブラリの整理、整合性、分析

• items retract-check — すべての DOI をCrossref の Retraction Watch データと照合し、撤回、懸念表明、訂正を確認します。通知 DOI と日付も表示されます。--check-retractions を指定すると library health ゲートに含められます。(ネットワークを利用します。)
• collections gaps — 引用グラフのギャップを分析します。コレクションから最も多く引用されている論文のうち、ライブラリにないものを順位付けし（OpenCitations + Semantic Scholar）、その後 import doi でインポートします。(こちらもネットワークを利用します。)
• items bibcheck <manuscript> — .tex または pandoc Markdown から \cite{}／@citekey を解析するか、.docx と .odt ファイルの Zotero 引用フィールドを読み取り、各キーをライブラリと照合します。不明なキーと曖昧なキーにはフラグが付きます。また、不明なキーに十分近い候補がある場合は、ライブラリ内の最も近いキーを参考候補として表示します。そのため、1 文字のタイプミスも .bib を手作業で検索せずに、修正対象を特定できます。CI では --fail-on-unknown を指定すると、終了コード 11 で終了します。--check-retractions を指定すると、引用された各アイテムの DOI も Crossref（ネットワーク）で検索し、引用行に撤回（重大）と懸念表明（高）を報告します。検索に失敗した場合はスキップとして報告され、--fail-on の指定時は終了コード 9 で終了します。
• tags audit — 大文字・小文字や表記の違いだけがあるタグを、アイテム数とすぐに実行できるマージコマンドとともにグループ化します。実際の 840 タグのライブラリでは、一度の実行で重複グループが 53 件見つかりました。
• library stats — アイテムの種類と年別の件数、上位の掲載誌、PDF の登録率、さらに --added-by month|year を指定した場合は追加時期別の内訳を、1 つのコマンドで確認できるダッシュボードです。
• items audit — PDF、要約、DOI、タグ、引用の主要フィールドが欠けているアイテムを数えて一覧表示します。--verify-files を指定すると、PDF が実際にディスク上に存在するか確認します。
• items duplicates — DOI またはタイトルから重複の可能性が高いアイテムを検出します（添付ファイルとノートは除外）。その後 duplicates resolve で安全にマージできます。
• items citekey-conflicts — LaTeX のビルドが失敗する前に、Better BibTeX キーの欠落や重複を検出します。
• items find — 重複をインポートする前に、DOI、ISBN、PMID、arXiv ID、引用キー、URL、OpenAlex の work ID、または完全一致のタイトルをローカルミラーで検索します。タイトルの照合では、大文字・小文字、空白、引用符やダッシュの表記、末尾の句点は区別しません。そのため、参考文献一覧からコピーしたタイトルでも一致します。検索全体で一致が見つからなかった場合は、ライブラリ内の最も近いタイトルまたはキーをスコア付きで別途一覧表示するため、タイプミスと論文の未登録を区別できます。これらは確認用の候補であり、一致した結果ではありません。セレクターは OR 条件で評価されるため、別のセレクターで一致した実行では、一致しなかったセレクターに対する近似候補は表示されません。

読書と統合

• items summarize — アイテムまたはコレクションについて、統合にすぐ使える範囲を絞った資料（引用情報＋概要＋自分の注釈＋上限付きの全文抜粋＋既知のメタデータ不足＋統合プロンプト）をまとめ、任意の LLM に渡します。zotio が予算を管理し、モデルを呼び出すことはありません。--focus "TERMS" で質問すると、各アイテムには代わりに、一致する PDF テキストの抜粋と注釈がランキング順で含まれ、アイテムキーと添付ファイルキーも付与されます。--max-chars は抜粋の文字数を、--max-annotations は注釈の数を制限するため、30 ページ目の調査結果が序論より優先されます。同期済みの PDF テキストがないアイテムは、「一致なし」と報告するのではなく、その旨を示します。
• annotations export · annotations timeline · annotations search — ハイライトとノートを Markdown または JSON として取得します（annotations export --output|-o はファイルに書き込みます）。日付順に並べたり、テキストで検索したりできます。
• reading-list — to-read タグを使ったキューで、次に読むものを選別するための add → start → done のライフサイクルを備えています。
• items note-template — アイテム用の、事前入力済みの Obsidian／Logseq 読書ノートを生成します。
• items open — アイテム、コレクション、または PDF への zotero:// ディープリンクを表示、または起動します（クロスプラットフォーム）。
• library wrapped — Zotero の年間レビューです。目玉となる件数、月ごとのリズムとピーク時のハイライト、種類の構成比バー、ハイライト（最も忙しかった日、最長連続記録、隠れた名作、最も注釈の多い論文、上位タグ）、主要な掲載誌と著者のフルネーム、PDF の収録状況を表示します。さらに、--card-style overview|rhythm|picks|cycle で選べる 4 種類のレイアウトで、共有可能な SVG カードを作成します（以下のカードは cycle で、3 種類すべてをクロスフェード表示します）。

エンリッチメント（外部 API から読み取り、Zotero に書き込み）

• items enrich — CrossRef → OpenAlex → Semantic Scholar から不足している DOI と概要を補完し、CrossRef から不足している引用情報を補完し、Unpaywall からオープンアクセス PDF を添付して、各アイテムの Extra フィールドに情報源を記録します。--missing-citation は、アイテムの種類で対応している空欄のみを補完します。プロバイダーが提供する巻、号、ページも対象です。--missing-mesh は、PMID があるアイテム、または PubMed が認識している DOI を持つアイテムについて、PubMed MeSH ディスクリプターを mesh/<descriptor> 形式の自動タグとして提案します。既定ではプレビューを表示し、PubMed の障害はエラーとして報告します。--validate は書き込みを行わず、CrossRef と照合してタイトル、年、レンダリングフィールドの不一致を報告するとともに、OpenCitations による DOI 登録の失敗も報告します。
• items preprint-check — 公開済みの CrossRef レコードが登録された arXiv プレプリントを見つけます。preprint-check fix は、ジャーナル DOI を使ってそれらを更新します。まずプレビューを行い、変更を記録し、競合する DOI を上書きすることはありません。

エクスポートと再現性

• items bibliography — 共有スコープをCSLスタイルでレンダリングするか、CSL-JSON、BibTeX、BibLaTeX、RISとしてエクスポートします。CSL-JSONでは、PandocやQuartoで使える一意のBetter BibTeX引用キーを使用します。--manuscript paper.tex（またはZoteroプラグインで作成した.docx／.odt）を指定すると、原稿で引用されたアイテムのみをエクスポートします。エクスポート形式では最初の引用順になりますが、CSLでレンダリングしたbibはスタイルの並べ替え順を維持します。引用キーが不明または曖昧な場合は、エクスポートを拒否します（終了コード11）。--scopeには、collection:KEY AND tag:NAMEのようにANDで結合したコホートを指定できます。
• collections export — コレクション全体とそのすべてのサブコレクションを、1つのBibTeX、RIS、またはCSL-JSONファイルとしてエクスポートします。サブツリー内のアイテムは再帰的に含まれます。ファイルにはコレクション階層は記録されません。
• export snapshot — 再現可能で中断・再開可能な、ページネーションを完全に処理するエクスポートです（デフォルトはJSONL、--format bibtex|ris|csljson）。ドリフト検出とスムーズなレビューの引き継ぎに使える、コンテンツマニフェスト<output>.manifest.json（ソート済みのキー＋バージョン＋sha256）を生成します。

最新性とスキーマ

• sync・watch・tail — ミラーを作成し、定期的な差分同期で最新の状態に保つか、リアルタイムの変更をストリーミングします。watch --healthはサイクルごとにlibrary healthの差分を取り、新たな検出結果を標準出力またはWebhookに報告します。ドリフトが発生したサイクルで通知されます。ライブラリのarXivプレプリントも監視するには、--health-check-preprintsを追加します。プレプリントに出版済みレコードが追加されると、preprint_publishedの検出結果として一度だけ報告されます。確認結果は--health-preprint-recheck（デフォルトは7d、最短は1h）の期間キャッシュされます。プロバイダーの障害はスキップとして記録され、問題なしとは判定されません。
• schema drift — Zoteroのアップグレード後、保存済みのベースラインと照合して、アイテムタイプ、フィールド、作成者フィールドの変更を検出します。

エージェント向けに設計

zotio は、MCP ホスト、CI ジョブ、またはシェルスクリプトが動作を開始する前に、安全性、新しさ、書き込み可能性を確認できるよう、機械可読な信頼モデルを公開します。

• 任意のコマンドで使える --agent：1つのフラグで JSON + コンパクト出力 + 非対話形式 + 色なしになります（書き込みを自動適用することはありません）。--json／--agent のもとで型付きエラーが発生すると、stdout にフラットな JSON オブジェクト {kind, code, message, hint?} が出力されます。変更に失敗した場合は ok:false のエンベロープが維持され、which で見つからなかった場合は {"matches":[]} が出力され、終了コード 2 で終了します。
• capabilities — コマンドレジストリ全体です。各コマンドには operation、data_sources、write_target、destructive、および事前条件の requires がタグ付けされています。複数の書き込み経路を持つコマンドでは、各経路のターゲットと事前条件も一覧表示します。
• agent-context — CLI 全体の構造化された説明です。レジストリと検出のヒント、exit_codes テーブル、コマンドごとではなく一度だけ掲載される global_flags、および3状態の mcp:read-only アノテーションを説明する annotation_semantics が含まれます。
• which "<capability in your words>" — 自然言語のクエリを、該当する処理を実行するコマンドに解決します。
• 安定したエンベロープ — すべてのコマンドで、変更計画／結果、検出結果、終了コードの契約がそれぞれ統一されています。

スコープの文法 — 読み取り、監査、エクスポート、拡充、および全文検索で共通の選択語彙です（search QUERY --fulltext --scope collection:KEY は、対象グループ内で順位付けと件数制限を行います）。

collection:KEY   tag:NAME   query:TEXT   item:KEY   saved-search:KEY
<arm> AND <arm>   # intersection, e.g. collection:KEY AND tag:NAME

複数の条件をすべて満たす項目だけを選択するには、AND（大文字で、両側にスペース）で条件をつなぎます。たとえば、zotio items enrich --missing-doi --scope 'collection:ABCD1234 AND tag:include' のように指定します。テキストは、AND の後に別の条件が続く場合にのみ分割されるため、query:trust AND safety は1つのクエリのままです。library は複数条件の組み合わせに含められません（終了コード 2）。評価できない保存済み検索の条件が含まれている場合、空として扱うのではなく終了コード 9 で拒否されます。

saved-search:KEY は、Zotero デスクトップが応答する場合、そのデスクトップによって評価されます。デスクトップに接続できない場合、またはローカル API へのアクセスが拒否された場合、zotio は同期済みの検索定義をローカルミラーに対して評価し、notice: 行を出力します。--data-source live を指定すると、フォールバックは無効になります。ローカル評価器は、テキストフィールド、作成者、タグ、コレクション、アイテムタイプ、および日付の条件に対応し、any/all の結合方法と子アイテムのフラグもサポートします。その他の条件（全文、ノート、入れ子の検索）を使用する検索は、該当する条件名を示して終了コード 9 で終了します。

終了コード（同じ表が SKILL.md と agent-context --json の exit_codes にあります）：

明示的な --help は終了コード 0 で終了します。

インストール

zotio は個別にインストールできる3つの要素で構成されています。CLI（エンジン。すべての処理はこれを通じて実行されます）、エージェントスキル（コーディングエージェント内で CLI を操作します）、MCP サーバー（Claude Desktop などの MCP ホストに CLI を公開します）。ほとんどの方には CLI が必要です。お使いのエージェントに応じて、スキルまたは MCP サーバーを追加してください。

1. CLI — zotio

Homebrew（macOS）：

brew install orgmentem/tap/zotio

これにより zotio と zotio-mcp MCP サーバーの両方がインストールされます。brew upgrade で新しいリリースが適用されます。

Linux（deb / rpm / apk）： apt/dnf/pacman リポジトリはありません。パッケージは GitHub リリースのアセットとして配布されています。dpkg -i、rpm -i、または apk add --allow-untrusted でインストールしてください。 インストールガイドには、最新バージョンとお使いのアーキテクチャを特定するスニペットがあります。

Windows（WinGet / Scoop）： winget install OrgMentem.zotio または scoop bucket add orgmentem https://github.com/OrgMentem/scoop-bucket && scoop install zotio。 どちらも zotio と zotio-mcp をインストールします。WinGet では、Microsoft がバージョン更新を反映するまで、リリース後しばらくの間、前のバージョンが提供される場合があります。Scoop はすぐに更新されます。

ビルド済みバイナリ： すべてのGitHub リリースには、cosign 署名付きチェックサムと SBOM を含む macOS、Linux、Windows（amd64/arm64）向けアーカイブが用意されています。展開して zotio を PATH に追加してください。macOS では Gatekeeper の隔離属性を解除し（xattr -d com.apple.quarantine zotio）、Unix では chmod +x zotio を実行してください。

ソースからインストール：

git clone https://github.com/OrgMentem/zotio && cd zotio && go build -o zotio ./cmd/zotio

その後、CLI の案内に従ってセットアップを進めてください。Zotero の検出、ローカル API の切り替え、任意の Web API キーの設定、初回同期、ヘルスチェックが行われます。

zotio init

2. エージェントスキル

このリポジトリに SKILL.md として同梱されている、目的を絞ったスキルです。コーディングエージェントが CLI を直接操作できるようにします（最も効率的な方法で、間に MCP サーバーを挟みません）。

おすすめ — skills CLI（Claude Code、Cursor、Codex、Cline、opencode、および40以上のエージェントに対応）：

npx skills add OrgMentem/zotio          # detect your agents and install
npx skills add OrgMentem/zotio --list   # preview without installing
npx skills add OrgMentem/zotio -g       # install globally (all projects)

手動での設定：

• Claude Code： SKILL.md を ~/.claude/skills/zotio/SKILL.md（またはプロジェクトの .claude/skills/zotio/）にコピーします。
• その他のエージェント： raw ファイル https://raw.githubusercontent.com/OrgMentem/zotio/main/SKILL.md を指定するか、エージェントのスキルストアに貼り付けます。

3. MCP サーバー — zotio-mcp

zotio-mcp は CLI と一緒に配布されています。macOS の Homebrew cask と各リリースアーカイブには、両方のバイナリが含まれています。次のように登録してください。

# Claude Code
claude mcp add zotero zotio-mcp -e ZOTERO_API_KEY=<your-key>

Claude Desktop 向けには、各リリースにプラットフォーム別の MCPB バンドルが含まれています。お使いのプラットフォーム用の .mcpb をダウンロードしてダブルクリックすると、Claude Desktop がインストールを案内します。

{
  "mcpServers": {
    "zotero": {
      "command": "zotio-mcp",
      "env": { "ZOTERO_API_KEY": "<your-key>" }
    }
  }
}

ZOTERO_API_KEY は、読み取り専用のローカルデスクトップ利用では省略可能です（ローカル API にキーは不要です）。書き込みを有効にしてグループライブラリにアクセスするには、設定してください。

認証

読み取りは Zotero デスクトップアプリの localhost:23119 に接続します。Zotero の実行中は API キーは不要です。まず、Zotero でローカル API を有効にしてください。Settings → Advanced → "Allow other applications to communicate with Zotero."

新しい個人ライブラリ項目の作成とその添付ファイルの保存は、ローカルデスクトップコネクターを使えば API キーなしで実行できます。既存項目に対する attachments add には、--via connector を指定しても Web API キーが必要です。この経路では、新しい添付ファイルを Web API 経由で対象項目に追加するためです。

編集を伴う書き込み（items update／delete／move、items enrich、tags の変更、vault push／pull／resolve、import apply の大半）は Zotero Web API 経由で実行され、キーが必要です。一度設定すれば、その後は設定不要です。

printf %s "$ZOTERO_API_KEY" | zotio auth set-token --stdin     # or export ZOTERO_API_KEY=<key>

キーは https://www.zotero.org/settings/keys で生成できます。Web API への初回書き込み時に、対象を示す一度限りの通知が stderr に出力されます。グループライブラリを含む、リモートの Web API 読み取りにもキーが必要です。サポートされている --data-source local の読み取りでは、デスクトップアプリやキーを使わず、同期済みミラーを利用します。zotio doctor を実行すると、書き戻しが利用可能かどうかを示す writes: 行を確認できます。

使用方法

CLI を直接使う

# 1. Verify Zotero is running and reachable
zotio doctor

# 2. Sync your library to local SQLite for offline search + analytics
zotio sync

# 3. See the shape of your library
zotio library stats

# 4. Certify it for a citation handoff (exit 11 if it fails the bar)
zotio library health --for citation --fail-on high

# 5. Search offline
zotio search 'automation trust' --fulltext --data-source local --json

# 6. Export annotations since a date as JSON for synthesis
zotio annotations timeline --since 2026-05-01 --json > since-may.json

コーディングエージェントでスキルを使う

上記の手順でインストールしたら、Claude Code で /zotio <query> を呼び出します。このスキルは CLI を直接操作します。MCP サーバーを介さない、最も効率的な方法です。

エージェントホストで MCP サーバーを使う

上記の手順で登録すると、MCP サーバーはエンドポイントごとに個別のツールを提供するのではなく、コマンドオーケストレーション用ファサード（command_search／command_run）を公開します。エージェントは人間と同じ方法で CLI を検出して操作できます（dev/adr/0001-mcp-command-surface.md を参照してください。ZOTIO_MCP_SURFACE でインターフェースを切り替えられます）。ローカルファイルを書き込むコマンドでは --dry-run が利用でき、annotations search も使用できます。ツールヒントは機能レジストリに基づいています。destructiveHint が true になるのは、破壊的なコマンドとローカルファイルを書き込むコマンドだけです。また、ローカルミラーのみを読み取るコマンドは openWorldHint: false を返します。さらに、Zotero のコンテキストをリソースとして提供します。具体的には、zotero://context、zotero://agent-context、zotero://status、zotero://schema、zotero://freshness、zotero://health/{scope}、zotero://capabilities、および範囲を限定したグラフリソース（collections/{key}/tree、items/{key}/children|attachments|context）です。ガイド付きプロンプト（prepare-library-health、prepare-import、sync-vault-safely、inspect-library、export-reading-notes、prepare-citation-export、synthesize）も提供します。

出力形式

zotio collections list                       # human table (JSON when piped)
zotio collections list --json                # JSON for scripting and agents
zotio collections list --json --select key,data.name   # only the fields you need
zotio collections list --dry-run             # no write of any kind; reads like this one still run
zotio collections list --agent               # JSON + compact + non-interactive + no color

ほかに、--csv、--plain（表形式がないコマンドではどちらも受け付けず、終了コード 2 を返します）、--quiet（何も出力せず、終了コードが答えになります）、--compact、--deliver stdout|file:<path>|webhook:<url> も利用できます。--deliver は --dry-run の場合も含め、コマンドの出力先を指定します。出力に存在しないフィールドを --select で指定すると、終了コード 2 を返します。

ヘルスチェックとトラブルシューティング

zotio doctor            # config, credentials, connectivity, cache freshness, writability
zotio desktop status    # is Zotero desktop running, and does its connector accept imports?

• doctor: connection refused — Zotero デスクトップアプリを開き、Settings → Advanced → "Allow other applications to communicate with Zotero." を有効にしてください。
• items missing-pdf／analytics／その他のミラー読み取りで終了コード 9 が返る — ローカルミラーが同期されていません。まず zotio sync を実行してください。synced_store の前提条件エンベロープにその旨が記載されています。
• annotations export で空のセクションが出力される — PDF の注釈は、外部アプリではなく Zotero 内蔵の PDF リーダーで作成する必要があります。
• citekey-conflicts でキーが見つからない — Better BibTeX 拡張機能をインストールしてください。引用キーは extra フィールドに保存されています。
• 認証エラー（終了コード 4） — zotio doctor で認証情報を確認し、echo $ZOTERO_API_KEY の結果を確認してください。

設定

設定ファイル：~/.config/zotio/config.toml。静的なリクエストヘッダーは [headers] の下に設定できます。コマンドごとの上書き設定が優先されます。

コマンドリファレンス

コマンドの一覧は zotio --help で確認できます。サブコマンドのヘルプは zotio <command> --help で確認できます。目的は分かっていてもコマンドが分からない場合は、CLI に直接問い合わせてください。

zotio which "export bibtex for a collection"

姉妹プロジェクト：papio

zotio は Zotero ライブラリを管理し、保護します。papio は文献の入手を担います。普段使っているブラウザーを通じて、オープンアクセスや所属機関の購読から、検証済みで来歴が追跡された PDF を見つけてダウンロードし、プレビューを確認してから zotio にインポートします。ライブラリに PDF のないアイテムがあれば、papio が補完します。

参考にしたプロジェクトとリソース

以下のプロジェクトやリソースを調査して開発しました。

• cli-anything-zotero — TypeScript
• 54yyyu/zotero-mcp — Python
• pyzotero — Python
• kujenba/zotero-mcp — Python
• jbaiter/zotero-cli — Python
• dhondta/zotero-cli — Python
• Combjellyshen/ZoteroBridge — TypeScript
• RaulSimpetru/zotero-library-mcp — Python
• introfini/mcp-server-zotero-dev — TypeScript
• piiinpiiins/zotero-mcp-local — Python
• mcp-for-zotero — ホステッドサービス

MIT ライセンスの下で公開されています。

Zotero は、Corporation for Digital Scholarship の登録商標です。zotio は独立したプロジェクトであり、Zotero または Corporation for Digital Scholarship とは提携しておらず、承認も受けていません。