zotero-library-mcp

zotero-library-mcp

Claude、Codex、ChatGPT が DOI、arXiv ID、ISBN を使って論文や書籍を Zotero ライブラリに追加し、コレクション、タグ、アイテムを管理できる MCP サーバーです。

このサーバーは、これらのクライアントで使用される次の両方の MCP トランスポートに対応しています。

• stdio（デフォルト）。Claude Code、Claude Desktop、Codex CLI/IDE、ChatGPT デスクトップアプリ向け
• Streamable HTTP。ホストされた ChatGPT アプリ、または任意のリモート MCP クライアント向け

ツール

論文の追加

• add_paper_by_doi — CrossRef で DOI を解決し、重複を検出したうえで論文を Zotero に追加します
• add_papers_by_dois — 一度に最大 50 件の論文をまとめて追加します
• add_paper_by_arxiv_id — arXiv ID でプレプリントを追加します（利用可能な場合は DOI を使用し、そうでない場合は arXiv のメタデータを使用します）
• add_item_from_metadata — 検証済みの手動入力メタデータから、対応する任意の Zotero アイテムタイプを作成します

書籍の追加

• add_book_by_isbn — Open Library で ISBN を解決し、重複を検出したうえで書籍を Zotero に追加します

検索と閲覧

• list_libraries — API キー所有者の個人ライブラリと共有グループライブラリを、ID およびキーの権限とともに確認します
• search_library — タイトル、著者、タグなどで Zotero ライブラリを検索します。start/limit によるページネーションに対応し、完全一致検索で結果がない場合はあいまい検索に切り替えます
• get_item_details — 任意のアイテムのメタデータ全体を表示します
• get_recent_items — 最近追加されたアイテムを一覧表示します
• get_unfiled_items — どのコレクションにも属していないアイテムを取得します
• search_fulltext — Zotero のメタデータとインデックス化された全文を検索します
• find_duplicates — DOI、ISBN、または正規化されたタイトルで重複アイテムを検索します
• list_attachments — すべての添付ファイルを一覧表示し、特定の PDF キーを選択します
• health_check — ライブラリの認証情報、アクセス権、ストレージ設定を確認します

読み取りと注釈

• get_item_fulltext — 一時パスを漏らさず、Zotero のインデックスまたは PDF から、長さを制限したプレーンテキストを返します
• get_bibtex — アイテム、コレクション、またはライブラリ全体を対象とした、読み取り専用の BibTeX/BibLaTeX エクスポートです
• save_bibtex — エクスポートを許可されたローカルパスに保存します
• get_annotations — 論文の PDF にあるすべてのハイライトと注釈を一覧表示します
• create_annotation — PDF 内のテキスト箇所をハイライトします（完全一致するテキストを検索し、Zotero リーダーに表示されるハイライトを作成して、確認用のプレビュー画像を返します）。スマートな重なり処理に対応しています。同一の箇所が完全に重複する場合は既存のコメントを更新し、その一部にあたる箇所には対照的なハイライト色を自動で設定します。
• add_note — アイテムにノートを追加します
• list_notes、update_note、delete_note — 既存のノートを管理します
• update_annotation、delete_annotation — 注釈を編集または削除します

ファイル添付

• attach_file — stdio 経由のローカルファイル、または HTTP 経由の ChatGPT ファイル入力を添付します
• download_pdf — リモート環境で安全に使用できる MCP ファイルリソースを返します
• save_pdf — PDF を許可されたローカルパスに保存します

コレクション

• list_collections — すべてのコレクションを一覧表示します（階層構造を含む）
• create_collection — 新しいコレクションを作成します（任意で親コレクションの下に作成できます）
• get_collection_items — コレクション内のアイテムを閲覧します。start/limit によるページネーションに対応しています
• add_to_collection — 既存のアイテムをコレクションに追加します
• remove_from_collection — アイテムをコレクションから削除します（ライブラリには残ります）
• rename_collection、move_collection — コレクションを再編成します

タグ

• list_tags — ライブラリ内のすべてのタグを一覧表示します
• add_tags — 1 つ以上のタグをアイテムに追加します（色の指定は任意です）
• remove_tags — アイテムからタグを削除します
• delete_tags — ライブラリ全体からタグを削除します
• set_tag_color — タグに色を割り当てます（Zotero のタグセレクターに表示されます）
• rename_tag — ライブラリ内のすべてのアイテムにあるタグの名前を変更します
• unset_tag_color — タグを削除せずに色を解除します

検証

• verify_items — 最近のアイテムを CrossRef と照合し、DOI の誤りやタイトルの不一致を再確認します

削除

• delete_item — ライブラリからアイテムを完全に削除します
• delete_collection — コレクションを完全に削除します
• trash_item、restore_item — 通常の整理には、元に戻せるゴミ箱操作を優先してください

このサーバーは、ChatGPT の企業ナレッジおよびディープリサーチで使用される、標準の読み取り専用 search および fetch ツールの形式も公開します。

前提条件

1. Zotero アカウント
2. 書き込み権限のある Zotero API キー：https://www.zotero.org/settings/keys
3. Zotero のライブラリ ID（同じページ、またはプロフィール URL に表示されています）
4. uv がインストールされていること

クイックスタート

Codex と ChatGPT デスクトップアプリ

Codex と ChatGPT デスクトップアプリは、同じ Codex ホスト上で MCP 設定を共有します。サーバーを一度追加します。

codex mcp add zotero \
  --env ZOTERO_LIBRARY_ID=your_library_id \
  --env ZOTERO_API_KEY=your_api_key \
  -- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

次に、Codex または ChatGPT デスクトップアプリを再起動します。Codex では /mcp を使って、zotero が接続されていることを確認します。ChatGPT デスクトップでは、設定 → MCP サーバーを開くと、同じサーバーを確認できます。

WebDAV ストレージを使用する場合は、WebDAV の設定例にある 3 つの ZOTERO_WEBDAV_* の値を追加します。デスクトップアプリが uvx を見つけられない場合は、which uvx が返すフルパスに置き換えてください。

サーバーは ~/.codex/config.toml に直接設定することもできます。

[mcp_servers.zotero]
command = "/full/path/to/uvx"
args = ["--from", "git+https://github.com/RaulSimpetru/zotero-library-mcp", "zotero-mcp"]
env_vars = ["ZOTERO_LIBRARY_ID", "ZOTERO_API_KEY", "ZOTERO_LIBRARY_TYPE", "CROSSREF_MAILTO", "ZOTERO_WEBDAV_URL", "ZOTERO_WEBDAV_USER", "ZOTERO_WEBDAV_PASSWORD"]
startup_timeout_sec = 30
tool_timeout_sec = 120

env_vars を使う場合は、それらの変数を含む環境から Codex／ChatGPT を起動します。意図的に値を設定ファイルに保存する場合は、代わりに [mcp_servers.zotero.env] を使用してください。

Claude Code

プラグインとしてインストールする方法がおすすめです。

/plugin install zotero --marketplace RaulSimpetru/zotero-library-mcp

古いバージョンの Claude Code では、最初に /plugin marketplace add RaulSimpetru/zotero-library-mcp を実行し、 次に /plugin install zotero@zotero-library-mcp を実行してください。プラグインを有効にすると、Claude Code から ライブラリ ID と API キー（任意の WebDAV および Unpaywall 設定を含む）を尋ねられます。API キーと WebDAV パスワードはシステムのキーチェーンに保存されます。新しいリリースを取得するには、/plugin marketplace update zotero-library-mcp を実行するか、/plugin でマーケットプレイスの 自動更新を有効にしてください。

プラグインのツール名は mcp__zotero__<tool> ではなく mcp__plugin_zotero_zotero__<tool> です。 以前のツール名を指定している権限ルールを更新してください。以前に claude mcp add で サーバーを追加していた場合は、そのエントリー（claude mcp remove zotero -s user）を削除し、 2 つのコピーが同時に実行されないようにしてください。

または、通常の MCP サーバーとして追加します。

claude mcp add zotero \
  -e ZOTERO_LIBRARY_ID=your_library_id \
  -e ZOTERO_API_KEY=your_api_key \
  -- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

WebDAV の設定

WebDAV ファイルストレージ（Synology、Nextcloud など）を使用するには、WebDAV 変数を含めます。

claude mcp add zotero \
  -e ZOTERO_LIBRARY_ID=your_library_id \
  -e ZOTERO_API_KEY=your_api_key \
  -e ZOTERO_WEBDAV_URL=https://your-webdav-server.com \
  -e ZOTERO_WEBDAV_USER=your_username \
  -e ZOTERO_WEBDAV_PASSWORD=your_password \
  -- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

Claude Desktop

これを claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "zotero": {
      "command": "/full/path/to/uvx",
      "args": ["--from", "git+https://github.com/RaulSimpetru/zotero-library-mcp", "zotero-mcp"],
      "env": {
        "ZOTERO_LIBRARY_ID": "your_library_id",
        "ZOTERO_API_KEY": "your_api_key",
        "ZOTERO_WEBDAV_URL": "https://your-webdav-server.com",
        "ZOTERO_WEBDAV_USER": "your_username",
        "ZOTERO_WEBDAV_PASSWORD": "your_password"
      }
    }
  }
}

注： Claude Desktop はシェルの PATH を引き継がないため、uvx のフルパスが必要です。ターミナルで which uvx を実行して確認してください。

ChatGPT ウェブ版（Apps SDK／開発者モード）

ChatGPT ウェブ版は、HTTPS の Streamable HTTP エンドポイントに接続します。HTTP トランスポートを使ってサーバーをローカルで起動し、Secure MCP Tunnel または別の認証済み HTTPS デプロイを通じてアクセスできるようにします。

ZOTERO_LIBRARY_ID=your_id ZOTERO_API_KEY=your_key \
  uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --allowed-host your-tunnel.example.com

MCP エンドポイントは https://your-tunnel.example.com/mcp です。ChatGPT で開発者モードを有効にして、開発者モードのアプリを作成し、その URL を MCP サーバー URL として入力します。現在の UI の操作手順については、OpenAI のChatGPT から接続するガイドを参照してください。

セキュリティ： 個人で使う場合に最も安全な構成は、MCP サーバーをループバックにバインドした OpenAI Secure MCP Tunnel です。HTTP モードでは、デフォルトですべてのサーバーパスの読み取りと書き込みが無効になります。attach_file は ChatGPT が認可したファイルオブジェクトを受け取り、download_pdf は不透明な MCP リソースリンクを返します。安全性に関するアノテーションは承認のヒントであり、認可の境界ではありません。

公開環境にデプロイする場合は、外部の OAuth 2.1 アイデンティティプロバイダーを設定します。サーバーは JWKS エンドポイントを使って JWT アクセストークンを検証します。

export ZOTERO_MCP_OAUTH_ISSUER=https://auth.example.com
export ZOTERO_MCP_OAUTH_RESOURCE=https://zotero.example.com
export ZOTERO_MCP_OAUTH_JWKS_URL=https://auth.example.com/.well-known/jwks.json
export ZOTERO_MCP_OAUTH_SCOPES=zotero:read,zotero:write

認可サーバーは OAuth/OIDC ディスカバリーメタデータを公開し、PKCE を使った MCP OAuth 2.1 フローをサポートし、ZOTERO_MCP_OAUTH_RESOURCE 向けのトークンを発行し、設定されたスコープを含める必要があります。OpenAI の認証ガイドを参照してください。すでに認証済みのゲートウェイの背後でのみテストする場合は、--allow-unauthenticated-http により、認証されていない非ループバックリスナーを明示的に許可できます。

このプロセスでは、引き続きサーバー側の Zotero API キーを 1 つ使用します。認証済みの各 MCP クライアントは、共有グループを含め、そのキーで利用可能なライブラリを対象にできます。クライアントに利用させるライブラリに限定したキーを使用してください。真のマルチユーザーサービスには、検証済みの OAuth ID を個別の Zotero 認証情報に対応付け、ユーザーごとの認可を適用する必要があります。このデプロイアーキテクチャは、個人用サーバーパッケージの対象外です。

HTTP デプロイでサーバーパスが本当に必要な場合は、制限されたルート内でのみ有効にしてください。

zotero-mcp --transport streamable-http \
  --allow-server-files \
  --file-root /srv/zotero-mcp/exports

HTTP の起動設定は環境変数でも指定できます。

CLI オプション	環境変数	デフォルト
--transport	ZOTERO_MCP_TRANSPORT	stdio
--host	ZOTERO_MCP_HOST	127.0.0.1
--port	ZOTERO_MCP_PORT または PORT	8000
--http-path	ZOTERO_MCP_HTTP_PATH	/mcp
--allowed-host	ZOTERO_MCP_ALLOWED_HOSTS（カンマ区切り）	ローカルホスト
--allowed-origin	ZOTERO_MCP_ALLOWED_ORIGINS（カンマ区切り）	ローカルオリジン
--stateless-http	ZOTERO_MCP_STATELESS_HTTP	false
--allow-unauthenticated-http	ZOTERO_MCP_ALLOW_UNAUTHENTICATED_HTTP	false
--allow-server-files	ZOTERO_MCP_ALLOW_SERVER_FILES	HTTP モードでは false
--file-root	ZOTERO_MCP_FILE_ROOTS（カンマ区切り）	なし

スタンドアロンで実行する

ZOTERO_LIBRARY_ID=your_id ZOTERO_API_KEY=your_key \
  uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp

個人ライブラリと共有グループライブラリ

環境変数ではデフォルトライブラリを選択します。ライブラリ引数を省略する既存の呼び出しは、引き続きこのデフォルトを使用します。

list_libraries()を呼び出すと、キー所有者の個人ライブラリと共有グループを確認できます。結果にはname、library_id、library_type、is_default、key_permissionsが含まれます。グループの結果はlimitとstartでページ分割されます。next_startがnullになるまで、次の結果を取得してください。デフォルトがグループの場合も、ライブラリの確認ができます。

その他のすべてのツールでは、library_idとlibrary_type引数を省略可能です。

list_libraries()
list_collections(library_id="123456", library_type="group")
search_library(query="ultrasound", library_id="123456", library_type="group")
get_item_details(item_key="<key from that group>", library_id="123456", library_type="group")
search_library(query="ultrasound")  # Uses the configured default again

ライブラリを選択するには両方の引数を渡し、選択しない場合は両方とも省略してください。グループ名ではなく、list_librariesが返すIDを使用してください。選択は1回の呼び出しにのみ適用され、環境や他のクライアントの対象を変更することはありません。並行して呼び出す場合も同様です。アイテムキーとコレクションキーは、選択したライブラリから取得する必要があります。ZoteroはAPIキーの権限とユーザーのグループ権限を適用します。グループへのリクエストが拒否された場合、個人ライブラリにフォールバックせず失敗します。health_checkでも同じ引数を指定でき、書き込みを行わずに特定のライブラリを確認できます。

グループの添付ファイルには、Zoteroの組み込みストレージを使用します。同じサーバーから共有グループにアクセスする場合でも、WebDAVを使用するのは設定済みの個人ライブラリのみです。

環境変数

変数	必須	説明
ZOTERO_LIBRARY_ID	はい	デフォルトのZoteroユーザーまたはグループライブラリID
ZOTERO_API_KEY	はい	読み取り／書き込み権限を持つAPIキー
ZOTERO_LIBRARY_TYPE	いいえ	デフォルトのライブラリタイプ：user（デフォルト）またはgroup
CROSSREF_MAILTO	いいえ	CrossRefのポライトプール用メールアドレス（APIへのアクセスが高速になります）
UNPAYWALL_EMAIL	いいえ	オープンアクセスPDF検索用の連絡先メールアドレス（デフォルトはCROSSREF_MAILTO）
ZOTERO_WEBDAV_URL	いいえ	ファイルストレージ用のWebDAV URL（例：https://dav.example.com）
ZOTERO_WEBDAV_USER	いいえ	WebDAVユーザー名
ZOTERO_WEBDAV_PASSWORD	いいえ	WebDAVパスワード
ZOTERO_MCP_OAUTH_ISSUER	いいえ	保護されたHTTPデプロイ用の外部OAuth/OIDC発行者URL
ZOTERO_MCP_OAUTH_RESOURCE	いいえ	正規のHTTPS MCPリソース／オーディエンスURL
ZOTERO_MCP_OAUTH_JWKS_URL	いいえ	JWTアクセストークンの検証に使用するJWKS URL
ZOTERO_MCP_OAUTH_SCOPES	いいえ	必須スコープ（カンマ区切り。デフォルトは読み取りと書き込み）
ZOTERO_MCP_FILE_ROOTS	いいえ	HTTPサーバーのパスが有効な場合に許可するルート（カンマ区切り）

注: ZOTERO_WEBDAV_*変数が3つすべて設定されている場合、設定済みの個人ライブラリの添付ファイルには、Zoteroの組み込みストレージの代わりにWebDAVを使用します。グループの添付ファイルには常にZoteroストレージを使用します。サーバーはZotero Desktopの動作に合わせて、WebDAVのベースURLに/zoteroを自動的に追加します。

バージョン0.10.2

• Claude Codeプラグインとしてインストールできるようになりました：/plugin install zotero --marketplace RaulSimpetru/zotero-library-mcp。
• ZOTERO_LIBRARY_TYPEが空の場合、デフォルト（user）を使用するようになりました。プラグインのインストール時に、未設定の省略可能な設定が空文字列として渡されるためです。

バージョン 0.10.1

• Zotero ストレージへのファイル添付が再び機能するようになりました（グループライブラリおよび WebDAV を使用しない構成）：Zotero は、Pyzotero がファイル名として送信したローカルパス全体を拒否します。アップロードの完了を確認するようになり、レート制限またはアップロード失敗を、空の添付ファイルを残すのではなく報告します。
• list_tags はすべてのタグを返します。Zotero のタグページネーションのメタデータは 200 件を超えると誤っているため、以前の一覧では残りのタグが抜けていました。
• 呼び出し間で不要なクエリパラメーターが引き継がれなくなりました（例：アイテムテンプレートの取得後に重複チェックを行うと、その種類のアイテムだけが検索されていました）。
• 「tags」という単語を含む検索やタグ名の変更で、クラッシュしなくなりました。
• ゴミ箱に入れたアイテムへのタグ付け、分類、ノートや注釈の編集が機能するようになりました。
• ハイライトが、オフセットのあるクロップボックスを持つ回転ページでも正しい位置に表示され、単語全体に一致し、同じ場所にある場合のみ重複を確認するようになりました。また、別の箇所をハイライトするのではなく、occurrence が指定されていないことを報告します。
• arXiv のインポートで、論文のどのバージョンの既存コピーも検出するようになりました。
• CrossRef のインポートでは、組織の著者と編集者が保持され、書籍、編集書籍、章、学位論文が適切なアイテムタイプに割り当てられるようになりました。Open Library の書籍では、著者を著作レコードから取得します。
• verify_items は DataCite の DOI（arXiv、Zenodo）、CrossRef のタイトル内の HTML、サブタイトルに対応しました。health_check は読み取り専用キーを write_access: false として報告します。
• BibTeX エクスポートで、Zotero の並び順と、ページ間で一意の citekey が保持されるようになりました。
• 子アイテム（添付ファイル、ノート、注釈）の一覧に 100 件の上限がなくなりました。リンクされた PDF はスキップされ、単独の PDF は読み取れるようになりました。
• 最後のタグ色を削除できるようになりました。|| を含むタグの削除は拒否されます。
• ホスト型 HTTP デプロイメントの堅牢性を強化しました。ダウンロードでは検証済み IP に接続し（DNS リバインディング対策）、JWKS の再取得にはレート制限を設け、一時ファイルには排他的に保存します。
• DOI のインポートで重複が作成されなくなりました。 Zotero の検索では DOI がインデックス化されないため、以前のチェックでは一致を検出できませんでした。インポートでは解決済みタイトルを検索し、DOI（Extra 内の DOI: 行を含む）を比較するようになりました。
• ISBN のインポートで、ハイフン付き ISBN で保存された書籍の重複が作成されなくなりました。 ISBN-10 と ISBN-13 の形式が相互に一致するようになりました。
• search_library は、添付ファイルやノートではなく論文を返します。
• レート制限された書き込みは再試行されません（再試行するとアイテムが重複する可能性があるため）。また、成功したと報告するのではなく失敗するようになりました。
• add_papers_by_dois(attach_pdfs=True) は PDF を並列でダウンロードします。
• search_fulltext と search はトップレベルのアイテムを検索するようになりました（約 20 倍高速）。
• ファジー検索と find_duplicates は、Zotero の増分同期（since=）で最新状態に保たれるライブラリキャッシュを再利用するため、繰り返しの呼び出しが 1 秒を大幅に下回るようになりました。
• CrossRef リクエストでは、CROSSREF_MAILTO が設定されていない場合、丁寧な利用者向けプールの連絡先として UNPAYWALL_EMAIL を使用し、レート制限されたリクエストを再試行します。
• create_annotation は、行をまたぐ引用を全体にわたってハイライトし、ページをまたいで occurrence をカウントし、PDF 独自のページラベルを使用します。
• DOI/arXiv のインポート時に添付する PDF のファイル名がアイテムタイトルに基づくようになり、PDF が添付されなかった理由も結果に表示されるようになりました。
• 一覧の出力で、12/1/1993 のような日付の正しい年が表示されます。
• health_check は library_type を user/group として返し、オープンアクセス PDF の検索（UNPAYWALL_EMAIL）が設定されているかどうかを報告します。
• restore_item に渡すキーを探すための新しい list_trash ツールを追加しました。
• アイテムキーを指定した場合の get_bibtex、rename_tag、get_recent_items、ファジー検索、find_duplicates が高速化しました。Zotero API への接続は呼び出し間で再利用されます。
• ライブラリ全体およびコレクションの get_bibtex エクスポートは、max_chars を超えるとダウンロードを停止します。
• get_item_fulltext は、ウェブスナップショットよりも PDF のインデックスを優先します。
• find_duplicates は items_scanned と scan_capped を報告します。
• アイテムに URL がない場合、search は zotero.org のアイテムリンクを代わりに使用します。
• ツールの説明を簡潔にしました。ライブラリの対象指定については、サーバーの指示内で一度だけ説明しています。

バージョン 0.10.0

• list_libraries で個人ライブラリと共有ライブラリを検出できます。
• 各ツール呼び出しで library_id と library_type を使ってライブラリを指定できます。既存の呼び出しでは、設定済みのデフォルトが引き続き使用されます。
• 並行呼び出しと入れ子になったエクスポートを、選択したライブラリのスコープ内に保持します。
• 共有ライブラリの添付ファイルには Zotero ストレージを使用し、設定済みの個人ライブラリに限り、個人用 WebDAV を使用します。
• 現在の依存関係のインポートと HTTP ログ記録を MCP stdio と互換性のある状態に保ちます。

新しいツールスキーマを読み込むには、アップグレード後に MCP 接続を再起動してください。

0.8 へのアップグレード

リモートクライアントが適切な安全性承認を適用できるよう、パスに書き込む操作を読み取り専用の操作から分離しました。

• get_bibtex(save_path=...) は save_bibtex(save_path=...) になりました。get_bibtex はデータを返すだけです。
• download_pdf(save_path=...) は save_pdf(save_path=...) になりました。download_pdf は不透明な MCP リソースリンクを返します。

get_bibtex と download_pdf の既存の読み取り専用呼び出しは、引き続き使用できます。

0.8.1

• クライアントが読み取る際、PDF と注釈プレビューのリソースで、正確な MIME タイプが維持されるようになりました。
• PDF のダウンロードで進行状況が報告され、明確な WebDAV タイムアウトエラーが返されるようになりました。
• health_check はライブラリを変更せずに、API キーの書き込み権限を報告します。
• サーバーの指示を短くし、クライアントが繰り返しコンテキストを使用する量を減らしました。

仕組み

1. DOI、arXiv ID、または ISBN を指定します。
2. サーバーが適切な API に問い合わせ、完全なメタデータを取得します。
   • DOI → CrossRef API
   • arXiv ID → arXiv API（DOI がある場合は CrossRef にフォールバックします）
   • ISBN → Open Library API
3. メタデータを Zotero のアイテム形式（タイトル、著者、ジャーナル／出版社、日付など）にマッピングします。
4. Zotero Web API を介して、Zotero ライブラリにアイテムを作成します。

ライセンス

MIT

mcp-name: io.github.RaulSimpetru/zotero-library-mcp