Zotero MCP Server：Zoteroを開かずに10,000件のPDFを約20 msで検索

Q: MCPサーバーが動作するにはZoteroを起動し続ける必要がありますか？

いいえ —— 検索と閲覧については不要です。コアはZoteroのデータディレクトリ（zotero.sqlite と storage/）を直接読むため、Zoteroを閉じていても、またそのマシンでZoteroデスクトップアプリが動作していなくても、インデックス作成と検索は機能します。ZoteroのローカルAPIを経由するのは3つの書き込みツール（アイテムのインポート、ノートの追加、タグ／コレクションの一括編集）だけなので、それらにはZoteroを開いている必要があります。

Q: Zotero MCPサーバーはJavaScriptだけでなくPythonもサポートしていますか？

はい。機能的に同等な2つのシェルがあります。JavaScript/Nodeユーザー向けのnpmの @docsagent/mcp-zotero と、Python 3.10+向けのPyPIの docsagent-mcp-zotero です。どちらも同じ8つのツールを同じスキーマ、エラーコード、書き込みゲートで公開し、同じバンドルされたC++コアを管理します。

Q: AIエージェントは私のZoteroライブラリを変更できますか？

許可した場合のみです。enableWrites が true に設定されていない限り、書き込みツールは登録されません。未確認の呼び出しはプレビューを返し、確認済みの書き込みはレート制限（既定で 30/hour）を受け、20件を超える複数アイテムのバッチには明示的な確認が必要です。

第一世代の Zotero MCP server を試したことがあるなら、あの儀式を覚えているはずです。Zoteroを起動し、ローカルAPIを有効にし、そしてクエリのたびにライブラリをメタデータ1件ずつ這うように進む。デモならそれで十分です。しかし、ライブラリに5,000件のPDFがあり、こちらが一文を打ち終える前にエージェントが20回の検索を投げてくる状況では、まったく十分ではありません。

新しい Zotero MCP Server —— @docsagent/mcp-zotero v4.0.1、2026年9月21日リリース —— は別物です。常駐するネイティブC++検索コアの上に**2つのシェル（JavaScriptとPython）**を載せ、Zoteroのデータディレクトリを直接読み取ります。Zoteroを開かずに検索が動作し、10,000件以上のPDFを抱えるライブラリは、Claude Code、Cursor、Codex、Claude Desktop、Gemini CLI、Qwen Code、Cline、その他あらゆるMCPクライアントにとってミリ秒単位の知識ベースになります。

これが新バージョンのガイドです。何が変わったのか、2つのランタイムへのインストール方法、エージェントが使える8つのツール、そして本当に大規模なライブラリでのベンチマーク数値を紹介します。

Zotero MCP Server 4.0 の新機能

2つのシェル、1つのコア。 同じツール契約が、npm上のTypeScriptパッケージ（@docsagent/mcp-zotero）としても、PyPI上のPythonパッケージ（docsagent-mcp-zotero）としても利用できます。すでに使っているランタイムを選べばよく、ツール、スキーマ、エラーコード、書き込みゲートは完全に同一です。
Zoteroを起動する必要がない。 C++コアは ~/Zotero/zotero.sqlite と storage/ ディレクトリを直接読み取るため、Zoteroを閉じていても —— あるいはそのマシンにZoteroがまったくインストールされていなくても —— インデックス作成と検索は動き続けます。
呼び出しごとのサブプロセスではなく、常駐サービス。 コアは http://127.0.0.1:23120/rpc でバックグラウンド動作し、ライブラリの変化に合わせてインデックスを再構築し、MCPクライアントの再起動をまたいでウォームな状態を保ちます。エージェントがコールドスタートのコストを払うことはありません。
大規模ライブラリのために設計。 転置インデックスによる BM25全文検索 + パッセージランキング が 1,000件以上のPDFで約15 ms。メモリ使用量はギガバイト級ではなく数百MB級です。
8つのMCPツール（読み取り5 + 書き込み3）。JSONスキーマで検証される引数、トークン予算、結果の重複排除、そして3層の書き込み安全ゲートを備えています。
2つのトランスポート。 ローカルのMCPクライアントには stdio。リモートにデプロイする場合は Streamable HTTP（/mcp）で、オリジンチェック、APIキーまたは OAuth 2.0（RFC 7662）認証、リクエスト単位の RBAC が付きます。
設定ファイルは1つ。 ~/.docsagent/config.json をJSシェル、Pythonシェル、C++コアが共有します。

仕組み：1つのネイティブコア上の2つのシェル

MCP Client (Claude Code / Claude Desktop / Cursor / Codex / Gemini CLI / Qwen Code / Cline)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← @docsagent/mcp-zotero  (TypeScript)  or  docsagent-mcp-zotero  (Python)
   · spec-driven tool schemas, argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
        │  JSON-RPC 2.0 over HTTP  ({coreHost}:{httpPort}/rpc)
        ▼
DocsAgent Core  (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/ directly
   · builds & serves the full-text index (BM25 + passage ranking)

この分離が重要です。シェルは薄い —— ツールスキーマを保持し、引数を検証し、トークン予算を守り、Zoteroのファイルには一切触れません。重い処理はC++のコアが担う。だからこそ同じエンジンが、npmパッケージとPyPIパッケージにバイト単位で同一の挙動を提供できるのです。

クイックスタート：3ステップでZoteroをAIエージェントに接続

オプションA —— JavaScript / npm

# 1. start the resident search core (background service)
npx @docsagent/mcp-zotero start
npx @docsagent/mcp-zotero status    # pid / endpoint / version

次に、MCPクライアントの設定（Claude Desktop、Cursor、Cline、Qwen Code など）にサーバーを追加します。

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "npx",
      "args": ["-y", "@docsagent/mcp-zotero"]
    }
  }
}

オプションB —— Python

# 1. install the Python shell (ships the same bundled core binaries)
pip install docsagent-mcp-zotero
docsagent-mcp-zotero core start
docsagent-mcp-zotero core status

そして同じ要領でPythonシェルを登録します。

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "docsagent-mcp-zotero",
      "args": []
    }
  }
}

MCPクライアントを再起動し、「私のZoteroライブラリはナトリウムイオン電池の容量劣化について何と言っていますか？」 のように尋ねてみてください。エージェントは search を呼び、zotero:KEY 引用付きのBM25ランキング済みパッセージを取得し、オープンウェブではなくあなたのPDFから答えます。

両方のCLIはコアのライフサイクルコマンド —— start、stop、restart、status（Pythonでは core サブコマンド配下、つまり docsagent-mcp-zotero core restart）—— も提供し、さらに /mcp をネットワーク越しに公開したいときの --transport streamable-http も備えています。

エージェントが呼び出せる8つのツール

ツール	種別	役割
`list_sources`	読み取り	検索可能なすべてのソースと、その機能・ドキュメント数。最初にこれを呼び出してください。
`search`	読み取り	アイテム、アノテーション、ノートを横断する検索。`ids` / `snippets` / `full` の深さ、タグ・年範囲・アイテム種別・著者・コレクションでのフィルタに対応。
`get_content`	読み取り	1件のエントリを、クエリでランキングされたパッセージ（`k`）またはオフセットページネーション付き全文として読む。
`get_metadata`	読み取り	メタデータ、要約、アノテーション、ノート、引用（BibTeX / CSL-JSON / フォーマット済み）。
`list_library`	読み取り	コレクション、アイテム、タグ、保存済み検索、単独ノートを閲覧。
`import_item`	書き込み	ローカルPDFのインポート、または DOI / ISBN / arXiv ID の解決。任意でコレクションへの自動分類も可能。
`add_note`	書き込み	MarkdownノートをZoteroの子ノートとしてアイテムに書き戻す。ロールバック対応。
`batch_modify`	書き込み	最大200件のアイテムに対してコレクションやタグを一括追加・削除。

enableWrites: true を設定しない限り、書き込みツールはそもそも登録されません。設定した場合でも、未確認の呼び出しはプレビューを返すだけでクォータを消費せず、確認済みの書き込みはレート制限（既定 30/hour）を受け、20件を超える batch_modify は requiresConfirmation を返します。エージェントはライブラリを一日中読めますが、黙って書き換えることはできません。

パフォーマンス：10,000件のPDF、42 GB、インデックス作成は約7分

このMCPサーバーのコアは、PapersGPTの検索ベンチマークの背後にあるのと同じインデックス・検索エンジンです。実際のZotero環境での数値は次のとおりです。

ライブラリ規模	生データ	インデックス作成	平均クエリ時間	メモリ（RSS）	インデックスサイズ
1,000件のPDF	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000件のPDF	42 GB	421 s（7 m 01 s）	19.5 ms	2.21 GB	901 MB

あえて控えめな構成 —— 4 cores / 8 GB RAM —— では、1,506件のPDF（4.5 GB）のインデックス作成に141秒かかり、その間プロセスが保持したメモリは227 MB、平均検索時間は~15 msでした。重要なのはこのパターンです。

インデックス作成はほぼ線形にスケールします。 PDFが10倍になれば構築時間も10倍 —— しかもそれは新しいドキュメントごとに一度払うだけで、質問ごとではありません。
検索は一定のままです。 1,000件で13 ms、10,000件で19.5 ms。論文を増やしてもエージェントは遅くなりません。
メモリは控えめなままです。 自動オフロードにより、42 GBのライブラリを約2 GBのRAMで検索可能に保ちます。
すべてオフラインです。 インデックス作成も検索もクラウド呼び出しを行わないため、飛行機の中でも、閉鎖された実験室ネットワークでも、情報統制下でも動作します。

「Zoteroを起動する必要がない」がワークフローを変える理由

従来のZotero MCPサーバーは、ZoteroローカルAPI（http://localhost:23119/api）を包む薄いラッパーです。Zoteroプロセスがなければ答えはありません。この単一の依存がすべてを規定します —— コンテナ、リモート開発マシン、ヘッドレススクリプト、SSHセッションからライブラリを検索することはできず、Zoteroが同期の途中にある間は検索できず、そして各呼び出しはインデックス参照ではなくリクエストの往復になります。

DocsAgentコアはデータベースを直接読むため、ワークフローの「読む」側がZoteroアプリから切り離されます。

	APIベースのZotero MCPサーバー	Zotero MCP Server 4.0
検索にZoteroの起動が必要	必要	不要
検索バックエンド	ZoteroローカルAPI呼び出し	ネイティブC++ BM25 + パッセージインデックス
10,000件のPDFのクエリ遅延	数百ミリ秒〜数秒	~20 ms
ランタイム	通常は1つ	JavaScript + Python
リモート / HTTPトランスポート	まれ	認証 + RBAC 付き Streamable HTTP
書き込みの安全性	通常は手動	3層ゲート + レート制限

ひとつ正直な注意点があります。書き込みは依然としてZotero自身のローカルAPIを経由します。そうすることでZoteroがライブラリの信頼できる唯一の情報源（source of truth）であり続けるからです。エージェントにPDFのインポート、ノートの追加、アイテムの再タグ付けをさせたい場合、その特定のステップではZoteroが起動している必要があります。インデックス作成、検索、閲覧は決して必要ありません。

ユースケース：研究者が実際にどう使っているか

Claude Code や Cursor でのエディタ内リサーチ。 論文を書きながら、エージェントに自分のライブラリからパッセージ、要約、BibTeXを直接引っ張ってこさせられます —— コピペも、ブラウザタブも不要です。
Codex や Gemini CLI でのターミナル中心の文献トリアージ。 「ライブラリ内で電力変換効率が20%を超えると報告している論文をすべて見つけて、Perovskiteコレクションに追加して」—— search の後に batch_modify です。
オフラインでの読書。 飛行機やフィールドでも、インデックスがローカルでクエリに答えます。ネットワークは不要です。
グループライブラリ。 zoteroGroups を研究室の共有ライブラリに向ければ、個人のコレクションと並べて検索できます。
エージェントスキル。 このプロジェクトは可搬な SKILL.md も公開しているため、スキルをサポートするエージェントに、ツール引数を推測させるのではなく「検索してから引用する」ワークフローを教え込めます。

プライバシーと安全性

あなたのPDFがマシンの外に出ることはありません。インデックス作成と検索は100%ローカルで、どのドキュメントもクラウドサービスに送信されません。書き込みを意図的に有効にした場合、それはゲートされ、プレビュー可能で、レート制限され、取り消し可能です。サーバーを意図的にHTTPで公開した場合は、開かれたポートではなく、オリジンチェック、トークン認証、リクエスト単位のRBACが得られます。

よくある質問

MCPサーバーが動作するにはZoteroを起動し続ける必要がありますか？

いいえ —— 検索と閲覧については不要です。コアはZoteroのデータディレクトリ（zotero.sqlite と storage/）を直接読むため、Zoteroを閉じていても、またそのマシンでZoteroデスクトップアプリが動作していなくても、インデックス作成と検索は機能します。ZoteroのローカルAPIを経由するのは3つの書き込みツール（アイテムのインポート、ノートの追加、タグ／コレクションの一括編集）だけなので、それらにはZoteroを開いている必要があります。

Zotero MCPサーバーはJavaScriptだけでなくPythonもサポートしていますか？

はい。機能的に同等な2つのシェルがあります。JavaScript/Nodeユーザー向けのnpmの @docsagent/mcp-zotero と、Python 3.10+向けのPyPIの docsagent-mcp-zotero です。どちらも同じ8つのツールを同じスキーマ、エラーコード、書き込みゲートで公開し、同じバンドルされたC++コアを管理します。

どれくらい大きなZoteroライブラリを扱えますか？

数千件のPDFを抱えるライブラリは日常的です。1,000件のPDF（4.2 GB）は約52秒でインデックス化され、約13 msでクエリできます。10,000件のPDF（42 GB）は約7分でインデックス化され、約19.5 msでクエリできます。インデックス構築時間はライブラリ規模におおむね比例して伸びますが、クエリ遅延はほぼ一定のままです。

私のZoteroライブラリはどこかにアップロードされますか？

いいえ。コアはインデックスを完全にあなたのマシン上で構築・提供し、検索にネットワークアクセスは不要です。あなたの論文に関する情報がPapersGPTや第三者に送信されることはありません。

AIエージェントは私のZoteroライブラリを変更できますか？

許可した場合のみです。enableWrites が true に設定されていない限り、書き込みツールは登録されません。未確認の呼び出しはプレビューを返し、確認済みの書き込みはレート制限（既定で 30/hour）を受け、20件を超える複数アイテムのバッチには明示的な確認が必要です。

どのAIクライアントがサポートされていますか？

任意のMCPクライアントです。プロジェクトはClaude Desktop、Claude Code、Cursor、Codex、Cline、Gemini CLI、Qwen Codeを文書化しており、stdioではなくリモートで接続するクライアント向けにStreamable HTTPトランスポートを提供しています。

以前のPapersGPT MCP構成とは何が違いますか？

以前の構成は、ZoteroローカルAPIを中心に作られた単一目的のブリッジでした。バージョン4.0はそれを常駐するC++検索コアに置き換え、一級のPythonシェルを追加し、Zoteroを起動せずに検索できるようにし、現実的な上限を「数百件の論文」から10,000件以上のPDFへと引き上げました。旧版の記事は歴史的な参考資料として今も公開されています。

はじめかた

npx @docsagent/mcp-zotero start

この1つのコマンドで、あなたのZoteroライブラリが、すでに使っているどのAIエージェントにとってもプライベートでミリ秒速の知識ベースに変わります。セットアップの注意点、ツールスキーマ、完全な設定リファレンスは docsagentリポジトリにあり、背景情報は MCPサーバーのページにあります。

同じエンジンをZotero自体の中で使いたいですか —— アプリ内チャット、AutoPilotによる一括読解、ローカルLLM？ Zotero AIプラグイン比較と PapersGPT をご覧ください。ターミナル中心のユーザーは Zotero CLIガイドもぜひどうぞ。