Zoteus

_{2026 年 9 月 6 日、メンテナー自身のライブラリで行われた実際のセッションです。ツール呼び出しはタイムラプスで表示されています。全編はこちらからご覧いただけます。}

インストール

ほとんどのクライアントでは、ダウンロードは不要です。クライアントは初回起動時に npx で Zoteus を取得します。MCP サーバーを使うのが初めてですか？docs/getting-started.md から始めてください。

クライアント	方法
Claude Desktop	お使いのシステム用のバンドル（zoteus-macos.mcpb、zoteus-windows.mcpb、zoteus-linux.mcpb）を最新リリースからダウンロードし、ダブルクリックします。設定画面（Settings → Extensions → Zoteus）とツールごとの権限設定を利用できるインストール方法です。
Claude Code	claude mcp add --transport stdio zoteus -- npx -y @oscardvs/zoteus
Claude Code、プラグインとして	/plugin marketplace add oscardvs/zoteus を実行し、次に /plugin install zoteus@zoteus を実行します。同じサーバーに加えて、Claude にページ番号付きの引用、エビデンステーブルの作成、引用、ライブラリの整理を教える4つのリサーチスキルが含まれています。任意の API キーは、/plugin → Zoteus → Configure options から設定します。Claude Desktop ではプラグインの設定は表示されないため、そちらでは .mcpb を使用してください。plugins/zoteus を参照してください。
Cursor、VS Code、Zed、Codex、Gemini CLI、その他の MCP クライアント	npx add-mcp @oscardvs/zoteus を実行するか、stdio サーバーとして npx -y @oscardvs/zoteus を手動で追加します。
ブラウザー版 claude.ai	ホストされた Zoteus または独自のリモートインスタンスを指すカスタムコネクターを追加します。
ChatGPT（ウェブ）	有料 ChatGPT プランで開発者モードを有効にする必要があります（Settings → Security and login）。次に、ホストされた Zoteus（https://mcp.zoteus.com/mcp）または独自のリモートインスタンスのサーバー URL を指定して、Plugins → Create app を選び、認証方法として OAuth を設定します。ChatGPT はリモートサーバーにしか接続しないため、npx によるインストールは適用されません。

続いて、Zotero デスクトップアプリを起動します。読み取りと、Zotero 10 以降での書き込みは、アプリが保持するすべてのライブラリ（自分のライブラリと、アプリに同期されたグループライブラリ）に対して行え、クラウドキーは不要です。同期、アプリが保持していないグループライブラリ、アプリを閉じているときに使用するには、Zotero API キーを追加します。

claude mcp add --transport stdio zoteus -e ZOTERO_API_KEY=xxxxx -- npx -y @oscardvs/zoteus

キーは zotero.org/settings/keys で取得できます。デスクトップアプリで、Settings → Advanced → "Allow other applications on this computer to communicate with Zotero" を有効にしてください。スクリーンショット付きのクライアント別手順については、zoteus.com/docs/connect-claude-to-zotero を参照してください。

デスクトップ拡張機能としてインストールした場合の更新。 手動でインストールした .mcpb（または古い .dxt）は自動更新されません。拡張機能の設定で Check for updates をオンにする（または ZOTEUS_UPDATE_CHECK=true を設定する）と、Zoteus は1日に1回 GitHub を確認し、新しいバージョンがある場合は zotero_whoami を通じてチャット内で通知します。お使いのシステム用の新しいバンドルをダウンロードし、再インストールしてください。この確認はデフォルトではオフです。npx によるインストールでは、常に公開済みの最新バージョンが実行されます。

機能

Zoteus は、名前空間 zotero_* のリサーチツールを提供します。キーワードまたは意味によるライブラリ検索、ページ位置情報付きの PDF からの抜粋取得、PDF のページや図の画像表示、任意の CSL スタイルによる citeproc-js を使った参考文献の書式設定、DOI または arXiv id によるアイテムの追加、バージョン管理された書き込みと元に戻せるゴミ箱を使ったアイテムの作成・編集・タグ付け・整理ができます。Zotero デスクトップアプリの起動中は、アプリが保持するすべてのライブラリへの読み取りと書き込みを直接行い、クラウド API キーは不要です。同期、アプリが保持していないグループライブラリ、アプリを閉じているときには、フォールバックとして Zotero Web API v3 を使用します。Zoteus は TypeScript で記述され、マシン上で動作し、MIT ライセンスで提供されています。

特長

• 自分のライブラリを検索。 タイトル、要旨、作成者、タグを対象としたキーワード検索とセマンティック検索を組み合わせ、PDFやメモ内の全文キーワード検索にも対応しています。一致した箇所はページ番号とともに返されます。自分のメモやPDFの注釈は紐づくアイテムの下にインデックス化されるため、「これはどこで異議を唱えたのか？」という問いにも検索で答えられます。ZOTEUS_INDEX_FULLTEXT を設定するか、zotero_index に fulltext:true を渡すと、設定済みの上限内で利用可能なPDF本文もインデックス検索の対象になります。そのため、要旨に記載されなかった主張も見つけられます。
• 引用をフォーマット。 Zoteus は、Zotero ライブラリの引用データを読み込み、CSL スタイルリポジトリにある任意の CSL スタイルで citeproc-js を使ってフォーマットします。
• 識別子で論文を追加。 DOI または arXiv ID を渡すと、Zoteus がメタデータを取得してアイテムを登録します。組み込みのリゾルバーですぐに利用でき、Zotero translation-server を使うと ISBN、PMID、URL にも対応します（docs/resolver.md を参照）。
• 変更を書き戻す。 アイテムの作成、編集、タグ付け、整理ができます。書き込みは楽観的ロックによる再試行付きでバージョン管理され、デフォルトでゴミ箱から復元できます。完全削除はオプトインで、確認が必要です。
• デスクトップアプリに直接書き込む。 アイテム、タグ、コレクション、保存済み検索、統合、添付ファイル、注釈の追加・編集、ゴミ箱への移動と復元は、クラウド API キーなしで、実行中の Zotero に対して行われます。自分のライブラリと、アプリが保持するすべてのグループライブラリが対象です。Zotero 10 以降では、一度許可する（「Always Allow」）だけで使えるローカル API を使用します。ローカル API が読み取り専用の Zotero 9 以前では、アイテムと注釈の追加にブラウザー拡張機能が使うコネクタープロトコルを使用します。アプリが保持していないグループライブラリや、アプリが実行されていない場合は、クラウド Web API をフォールバックとして使用します。
• PDF に注釈を付け、ファイルを添付。 zotero_annotate は、ハイライト、下線、メモを追加します。これらは Zotero PDF リーダーが作成するものと同じオブジェクトです。引用箇所を指定すると、Zoteus がPDF内でその位置を特定し、折り返しやハイフネーションも考慮して、該当する行に注釈を固定するため、ページ座標は不要です。zotero_attach_file は、ローカルファイルまたはURLを任意のアイテムに添付ファイルとして保存します。
• PDF に基づいて主張を裏付ける。 zotero_get_fulltext は、該当箇所を文字オフセット、最も近い見出し、ページ位置情報とともに返します。Zotero がPDFやEPUBをインデックス化していない場合は、実行中のデスクトップアプリまたはZotero独自の保存フォルダーから、その場でテキストを抽出するため、1分前に追加したファイルもすぐに読めます。PDFの目次（outline:true）や、指定したページ範囲のテキストもオンデマンドで返すため、400ページの書籍を読むときも、書籍全体を返す1回の呼び出しではなく、少数の小さな呼び出しで済みます。
• ページを見る。 zotero_pdf_images は、モデルが見られるようPDFの任意のページを画像としてレンダリングします。これにより、図、表、数式、テキストレイヤーのないスキャンページも確認でき、pdfimages のように、ページに埋め込まれた図もそれぞれページ上の位置とともに抽出します。テキストの読み取りにも使う同じ pdfjs で描画するため、すでにインストールされているもの以外は必要ありません。
• 文献をたどる。 zotero_scholar は、OpenAlex を通じて論文の参考文献、被引用文献、関連文献を調べます。OpenAlex が利用できない場合は Crossref にフォールバックし、該当文献がすでにライブラリにあるかどうかも示せます。
• 参考文献リストをインポートし、重複を見つけて統合。 zotero_import は、translation-server なしで、BibTeX、RIS、CSL-JSONをテキストまたはファイルから読み込み、PDFの冒頭ページから DOI または arXiv ID を特定し、保存前にライブラリに既存のコピーがないか確認できます。zotero_merge_items は重複を1つのレコードに統合します。デフォルトではプレビューを表示し、マスターにない情報だけを補い、タグ、コレクション、関連情報を統合し、メモと添付ファイルの親を付け替え、内容が空になったコピーをゴミ箱に移動します（docs/importing-bibliographies.md、docs/duplicates-and-merging.md を参照）。
• オープンアクセス版と撤回通知。 OpenAlex がオープンアクセスのPDFを把握している場合、zotero_scholar がそれを報告します。zotero_attach_file は DOI からそのPDFを取得して添付し、どの版かを記録できます。また、zotero_scholar は Crossref と OpenAlex の撤回・訂正レコードも、判定ではなくレコードとして報告します（docs/open-access-pdfs.md、docs/retraction-notices.md を参照）。
• エビデンステーブルと Word 文書。 zotero-evidence-table プロンプトと zotero_evidence_table を組み合わせると、収集した箇所を Markdown または CSV の表にまとめられます。引用文が参照先の箇所から逸脱することはありません。zotero_word_document は、引用を有効な Zotero フィールドコードとして含む .docx を作成します（docs/evidence-tables.md、docs/word-documents.md を参照。Word でフィールドを更新する動作は、まだ確認されていません）。
• スキャン、複数のライブラリ、ローカル埋め込み。 zotero_get_fulltext は、オプションのOCRエンジンを通じて、テキストレイヤーのないPDFを読み取ります（docs/ocr.md）。1つのデータディレクトリにライブラリごとの検索インデックスが保存され、zotero_semantic_search では複数のライブラリを一度に検索できます（docs/multiple-library-indexes.md）。また、ZOTEUS_EMBEDDINGS=ollama を設定すると、API キーなしでローカルの Ollama デーモンを通じて埋め込みを生成できます（docs/ollama.md）。zoteus index build は、コマンドラインからヘッドレスでインデックスを構築します。
• エージェントのサポート。 構造化出力に対応する34個のツール、MCP リソースとプロンプト、さらに code-execution-with-MCP パターン向けに生成されたツールツリーを備えています。

仕組み

1. 1つの npx コマンド、またはワンクリックの .mcpb でインストールします。
2. デスクトップアプリを実行してキー不要のローカルアクセスで接続するか、Zotero API キーを貼り付けます。
3. 質問します。 MCP クライアントで、ライブラリを検索し、引用し、追加し、整理できるようになります。

Zoteus は実行中の Zotero デスクトップアプリを検出して、アプリと直接通信します。読み取りにはキー不要のローカル API を使用します（PDF 全文、保存済み検索の結果、セマンティック検索インデックスの構築）。書き込みには、アプリが保持するすべてのライブラリに対してアプリ自体を使用します（インポート、編集、タグ、コレクション、マージ、添付ファイル、注釈、ゴミ箱）。フォールバックはクラウド Web API v3 です。同期、アプリが保持していないグループライブラリ、およびアプリが実行されていないときの書き込みには、引き続きクラウドが必要です。詳細はdocs/writing.mdをご覧ください。

グループライブラリへの書き込み。 デスクトップアプリが保持するグループ（Zotero 10 以降）には、クラウドキーなしでアプリ経由で書き込みます。それ以外のグループにはクラウド経由で書き込みます。その場合、そのグループへの読み書きアクセス権を持つ ZOTERO_API_KEY が必要です。どちらの場合も、グループの設定でライブラリの編集が許可されている必要があります。zotero_groups の数値の library_id でグループを指定してください（library_type:"group" だけでは不十分です）。コレクションキーも同じグループから取得してください。グループライブラリをご覧ください。

まず、検証済みの箇所を1つ確認します。 クライアントと接続方法を選び、検索の準備状況を確認してから、箇所を取得して検証してください。ライブラリ全体のインデックスは必要ありません。ローカルのみの PDF、WebDAV、スキャンした PDF については、PDF の利用可能性をご覧ください。

セマンティック検索の設定。 最初の zotero_semantic_search では、バックグラウンドでライブラリのインデックスを構築します。非常に大きなライブラリでは、自分で zotero_index（action:"build"）を実行し、完了するまで action:"status" をポーリングすることもできます。構築時には、他の読み取りと同じローカル優先の経路でライブラリをページ単位で取得するため、デスクトップアプリの実行中はクラウド API キーは不要です。個人ライブラリと、Zotero 10 以降ではアプリが保持するすべてのグループライブラリが対象です。アプリを閉じている場合、およびアプリが保持していないグループにはキーが必要です。

大規模なライブラリでの API 経由の埋め込み。 1万アイテムのライブラリの全文構築では、数万件のリクエストが発生します。デフォルトのペースでは、利用プランにかかわらず、リクエスト速度は OpenAI の 1 分あたりのトークン数の上限に達します。レート制限されたリクエストは構築に失敗するのではなく、待機して再試行します。また、構築が完了せずに終了しても、インデックス化した内容はすべて保持されます。zotero_index action:"build" を再度実行すると再開し、まだベクトルのない箇所だけを埋め込みます（最初からやり直すのは action:"refresh" です）。あらかじめ速度を調整するには、ZOTEUS_EMBED_BATCH_SIZE=256 と ZOTEUS_EMBED_BATCH_DELAY_MS=8000 を設定します。docs/semantic-search.mdをご覧ください。

ベクトルによるランキングはオプトインです。 キーワード（BM25）検索は、どの環境でもすぐに使えます。デバイス上でのベクトル処理には @huggingface/transformers が必要ですが、デスクトップ拡張機能のバンドルには含められません（onnxruntime のネイティブバイナリを含む依存関係ツリーは約 700 MB です）。専用ディレクトリにインストールし（mkdir -p ~/.zoteus-deps && cd ~/.zoteus-deps && npm init -y && npm i @huggingface/transformers）、ZOTEUS_TRANSFORMERS_PATH に ~/.zoteus-deps/node_modules を設定してください。npm i -g は使わないでください。Claude Desktop はサーバーを内蔵の Node で実行するため、バージョン管理ツール配下にグローバルインストールしても、拡張機能が実行しない Node の隣に配置されるだけです。ベクトルを利用できない場合、Zoteus は何も返さずに済ませるのではなく、zotero_index のステータス、zotero_whoami、zotero_semantic_search でその旨を通知します。docs/semantic-search.mdをご覧ください。

設定

変数	デフォルト	用途
ZOTERO_API_KEY	none	クラウド認証（同期、グループ、デスクトップアプリなしでの書き込みに使用。それ以外では任意）
ZOTEUS_LOCAL	auto	auto|on|off：Zotero デスクトップアプリを使用します（読み取りと個人ライブラリへの書き込み）
ZOTEUS_LOCAL_API_KEY	none	Zotero 10+ のデスクトップ書き込みキーを事前に設定します（設定しない場合は、アプリ内で一度だけ付与されます）
ZOTEUS_EMBEDDINGS	local	セマンティック検索用の local|ollama|openai|gemini|off
ZOTEUS_EMBEDDING_MODEL	プロバイダーのデフォルト	プロバイダーが埋め込みに使用するモデルです。local も含みます。ドイツ語またはその他の多言語ライブラリには Xenova/multilingual-e5-small、デフォルトでは Xenova/all-MiniLM-L6-v2 を使用します
ZOTEUS_EMBEDDING_DTYPE	fp32	オンデバイスモデルの重みの精度です。q8 を指定すると、Xenova/multilingual-e5-small のダウンロードサイズは 465 MB ではなく 129 MB になります。fp32 を超える値は埋め込みモデルの識別情報に含まれるため、変更すると再ビルドが必要です
ZOTEUS_EMBED_BATCH_SIZE	32	1 回の埋め込み呼び出しあたりの文章数です。API プロバイダーがリクエスト全体を拒否する場合は値を下げてください（OpenAI は 1 リクエストあたり 300K トークンを超えると 400 を返します）
ZOTEUS_EMBED_BATCH_DELAY_MS	0	埋め込み呼び出しの間隔です。API プロバイダーが大規模なビルドをレート制限する場合は値を上げてください。256 と 8000 を組み合わせると、全文ビルドを 1 分あたり約 400K トークンに抑えられます
ZOTEUS_INDEX_OWN_WORDS	true	自分で作成した子ノートと PDF 注釈を、検索可能な文章としてインデックスに登録します
ZOTEUS_INDEX_FULLTEXT	false	セマンティック検索のために PDF の本文をインデックスに登録します（オプトイン。コストがかかります）
ZOTEUS_INDEX_BACKEND	auto	検索インデックスの保存先です。auto|sqlite|memory を指定します。Node 22.13+ では auto は SQLite（FTS5）を使用します。大規模なライブラリにはこちらが必要です
ZOTEUS_TRANSFORMERS_PATH	none	インストール先から @huggingface/transformers が見つからない場合に、local 埋め込み用の同パッケージを検索する場所です（デスクトップ拡張機能）
ZOTEUS_LOG_FILE	none	ターミナルなしで動作するサーバー向けに、すべてのログ行をこのファイルに追記します
ZOTEUS_ALLOW_DELETE	false	true に設定する必要があります。そうでない場合、zotero_delete_items はすべての呼び出しを拒否します。ただし、ZOTEUS_READ_ONLY=true でない限り、ツールは一覧に表示されます

全項目については docs/configuration.md をご覧ください。共有インスタンスまたはリモートインスタンスを実行する場合は、docs/remote-oauth.md をご覧ください（OAuth リモートをループバック上、または独自のプロキシの背後でセルフホストします）。

ドキュメント

zoteus.com/docs · Claude を Zotero に接続する · ChatGPT を Zotero に接続する · レビュー チーム向けのグループライブラリ · Zoteus と zotero-mcp の比較

このリポジトリ内：はじめに · 設定 · インポートとリゾルバー · 参考文献のインポート · 重複とマージ · アーキテクチャ · 安全な書き込み · 脅威モデル · 引用 · Word 文書 · エビデンステーブル · セマンティック検索 · 複数のライブラリインデックス · Ollama エンベディング · OCR · 学術的コンテキスト · オープンアクセス PDF · 撤回通知 · コマンドライン · ラボのセットアップ · コード実行 · デプロイ · アンインストール

Zoteus は、MCP レジストリ（MCP Registry）に io.github.oscardvs/zoteus として登録されており、mcpservers.org および Citation Styler のZotero MCP プロジェクト一覧にも掲載されています。

アンインストール

Zoteus は、生成したすべてのデータ（検索インデックス、デバイス上のモデルの重み、更新確認キャッシュ、許可されたローカル API キー）を 1 つのディレクトリに書き込みます。このディレクトリは、ZOTEUS_DATA_DIR を設定した場合はその場所、それ以外の場合は OS の既定のアプリケーションデータパスです。サーバーを停止し、MCP クライアントの設定から削除してから、そのディレクトリを削除してください。Zotero ライブラリは別の場所にあり、ここから影響を受けることはありません。手順とプラットフォームごとのパスについては、docs/uninstall.mdをご覧ください。

プライバシー

Zoteus は、お使いのマシンまたは設定したサーバーで実行されます。使用状況のログ記録は、デフォルトでオフになっています。ツールの結果は選択した AI クライアントに送信され、有効にした機能は、必要に応じて Zotero や学術情報、PDF、エンベディングの各サービスに接続します。ポリシーの全文は、PRIVACY.mdをご覧ください。

貢献

貢献を歓迎します。詳細はCONTRIBUTING.mdをご覧ください。Zoteus は MIT ライセンスで提供されています。

謝辞

Model Context Protocol、Zotero Web API、citeproc-js、および Citation Style Language を基盤に構築されています。Corporation for Digital Scholarship / Zotero とは提携しておらず、承認も受けていません。

citeproc-js は Citation Style Language を実装しています。（c）Frank Bennett。Common Public Attribution License 1.0 に基づき使用しています。https://citationstyles.org/ 依存関係に関する通知はTHIRD_PARTY_NOTICES.mdにまとめられています。