MCP Zotero

MCP Zotero

注記： これは非公式のコミュニティプロジェクトであり、ZoteroチームまたはCorporation for Digital Scholarshipとの提携、承認、サポートはありません。「Zotero」はCorporation for Digital Scholarshipの登録商標です。

Zoteroと連携するためのModel Context Protocolサーバーです。任意のLLMからZoteroライブラリに完全にアクセスできます。検索、整理、DOIによる論文の追加、PDFのインポート、全文の閲覧、Word文書へのリアルタイムの引用挿入が可能です。

もともとは、Abhishek Kaliaによるmcp-zoteroをベースにしています。 その後、このプロジェクトは新しいアーキテクチャ、ツール数の増加（5個から15個）、引用の挿入、PDF管理、Claudeスキルのサポートを含め、大幅に書き直されました。

仕組み

このサーバーは、外部ドキュメントなしであらゆるLLMが利用できるように設計されています。接続時に、MCPのinstructionsフィールドを通じてワークフローの手順を送信し、各ツールの説明には相互参照と使用方法が含まれます。このサーバーを初めて利用するLLMでも、ツール一覧から論文の追加から引用付きWord文書の作成までのワークフロー全体を把握できます。

高度なユースケース（PDFのアップロードポリシー、引用スタイルのガイダンス、情報源の透明性）向けに、Claude.ai Projects用のClaudeスキルも用意されています。ただし、スキルは任意です。MCPサーバーは単体で必要な情報をすべて提供します。

ローカルLLMとリモートLLM

シナリオ	MCP サーバー	スキルが必要ですか？
ファイルシステムにアクセスできるLLM（Claude Code、LM Studioなど）	15個すべてのツール	いいえ
ファイルシステムにアクセスできないLLM（Claude.ai Projects、Claude Desktop）	APIツール（検索、追加、メタデータ）	引用の挿入には必要

ファイルシステムにアクセスできるLLMは、ディスク上の.docxファイルを読み書きするinject_citationsを含め、すべてのツールを直接利用できます。

Claude Desktopなど、MCPには接続できてもローカルでファイルを生成できないLLMは、付属のClaudeスキル（skills/zotero-skill-mcp-integrations/）を利用できます。このスキルは、サンドボックス内だけで引用の挿入を行います。MCPツールがすべてのZotero API操作を処理し、スキルが文書の組み立てを担当します。

Claudeスキルのセットアップ（Claude.ai ProjectsおよびClaude Desktop向け）

1. 最新のGitHubリリースからスキルの.zipをダウンロードします
2. 展開したフォルダーをClaude.ai Projectにスキルとしてアップロードします
3. スキルを使うと、ローカルのファイルシステムにアクセスすることなく、サンドボックス内で直接引用を挿入できます

セットアップ

Node.js 22以降が必要です。

このサーバーは、公式のMCP Registryに io.github.Xevos117/mcp-zoteroとして登録されています（2.0.2以降の最初のリリースから）。そのため、レジストリに対応したクライアントはそこから検索してインストールできます。以下の設定は、あらゆるMCPクライアントで動作します。

1. Zoteroの認証情報を取得します。

   # Create an API key at https://www.zotero.org/settings/keys
   # (enable library read/write + file access)
   # Then retrieve your user ID:
   curl -H "Zotero-API-Key: YOUR_API_KEY" https://api.zotero.org/keys/current
   

2. 環境変数を設定します。

   export ZOTERO_API_KEY="your-api-key"
   export ZOTERO_USER_ID="user-id-from-curl"
   export UNPAYWALL_EMAIL="[email protected]"   # Optional: enables OA PDF lookup via Unpaywall
   export UNSAFE_OPERATIONS="none"           # Optional: "none" | "items" | "all" (see below)
   

グループライブラリを指定する

デフォルトでは、サーバーは個人用のZoteroライブラリ（/users/<ZOTERO_USER_ID>/...）を対象にします。 代わりにグループライブラリを対象にするには、環境変数を2つ追加で設定します。

変数	値	必須ですか？	デフォルト
ZOTERO_LIBRARY_TYPE	user | group	いいえ	user
ZOTERO_LIBRARY_ID	数値のライブラリID	type=groupの場合は必須。それ以外の場合はZOTERO_USER_IDにフォールバックします	—

グループライブラリの例：

ZOTERO_API_KEY=...
ZOTERO_USER_ID=12345               # optional for groups: used by get_user_id and per-call library_type="user"
ZOTERO_LIBRARY_TYPE=group
ZOTERO_LIBRARY_ID=6178978          # the group ID

ZOTERO_API_KEYのAPIキーには、対象のグループライブラリへのアクセス権が必要です。キーの生成またはスコープ設定は、https://www.zotero.org/settings/keys で行ってください。

ZOTERO_LIBRARY_TYPE=groupが設定されているのにZOTERO_LIBRARY_IDが設定されていない場合、またはライブラリIDが数値でない場合、サーバーは起動を拒否します。

呼び出しごとのライブラリの上書き

すべてのツールでは、環境変数のデフォルト値をその呼び出しに限って上書きする、次の2つの引数を指定できます。

• library_type — "user" または "group"
• library_id — 数値のライブラリ ID

解決順序：呼び出しごとの引数 > 環境変数 > 暗黙のデフォルト値（user、ZOTERO_USER_ID）。library_id は数値でなければなりません。ユーザーライブラリ用に設定されたサーバーで library_type を group に上書きする場合は、library_id が必要です。グループサーバーで library_type を user に上書きし、library_id を指定しない場合は、ZOTERO_USER_ID が使用されます。

呼び出しごとの上書きにより、LLM は API キーでアクセスできる任意のライブラリを利用できます。公開するライブラリだけにキーのアクセス範囲を制限してください。削除は引き続き UNSAFE_OPERATIONS によって制御されます。

これにより、再起動せずに、1つの MCP インスタンスで複数のライブラリ（たとえば、ステージング用のグループと最終出力用のグループ）を対象にできます。

// First call targets the staging group
{
  "tool": "add_items",
  "args": {
    "items": [...],
    "library_type": "group",
    "library_id": "5597114"
  }
}

// Second call targets DART-output (different group)
{
  "tool": "add_items",
  "args": {
    "items": [...],
    "library_type": "group",
    "library_id": "6178978"
  }
}

環境変数

変数	必須	説明
ZOTERO_API_KEY	はい	Zotero Web API v3 の API キーです。zotero.org/settings/keys で、ライブラリの読み取り／書き込みとファイルアクセスの権限を付与して作成してください。
ZOTERO_USER_ID	はい	Zotero の数値ユーザー ID です。curl -H "Zotero-API-Key: KEY" https://api.zotero.org/keys/current で取得できます。
UNPAYWALL_EMAIL	いいえ	Unpaywall API リクエスト用のメールアドレスです（レート制限ポリシー）。add_items_by_doi と find_and_attach_pdfs で OA PDF の検索が有効になります。設定されていない場合、OA PDF 機能は通知なくスキップされます。
UNSAFE_OPERATIONS	いいえ	破壊的操作（削除）を制御します。下記の危険な操作を参照してください。デフォルト：none（すべての削除をブロック）。

危険な操作

デフォルトでは、MCP サーバーは削除を一切許可しません。これは、LLM がライブラリからアイテムやコレクションを誤って削除するのを防ぐための安全対策です。

削除を有効にするには、UNSAFE_OPERATIONS 環境変数に次のいずれかの値を設定してください。

値	delete_items	delete_collection	使用例
none（デフォルト）	ブロック	ブロック	セーフモード — 削除は一切できません
items	許可	ブロック	アイテムの削除を許可し、コレクション構造を保護します
all	許可	許可	フルアクセス — アイテムとコレクションを削除できます

重要な注意事項：

• UNSAFE_OPERATIONS が未設定、空、または認識されない値に設定されている場合、デフォルトの none が適用されます。
• 値の大文字・小文字は区別されません（例：ALL、Items、NONE も使用できます）。
• delete_items はアイテムを完全に削除します。Zotero Web API の複数アイテム DELETE はアイテムを Zotero のゴミ箱に移動しないため、デスクトップクライアントから復元できません。
• delete_collection はコレクション（フォルダー）だけを削除します。内部のアイテムは削除されず、ライブラリに残ります。
• all の値には、アイテムとコレクションの両方の削除が含まれます。コレクションの管理には、アイテムレベルのアクセスが本質的に必要なためです。

設定例：

{
  "mcpServers": {
    "zotero": {
      "command": "npx",
      "args": ["-y", "@xevos117/mcp-zotero"],
      "env": {
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "ZOTERO_USER_ID": "YOUR_USER_ID",
        "UNSAFE_OPERATIONS": "items"
      }
    }
  }
}

Claude Desktop との連携

Claude Desktop 拡張機能としてインストール（ワンクリック）

1. 最新リリースからmcp-zotero.mcpbをダウンロードします （2.0.2以降の最初のリリースから利用できます）。
2. ファイルをClaude Desktopで開き（macOSまたはWindows。たとえばダブルクリック）、インストールダイアログで確認します。 バンドル自体はプラットフォームに依存しないため（manifest.jsonにはmacOS、Windows、Linuxが記載され、CIでは Linux上で実行されます）、ほかのMCPB対応クライアントでもインストールできます。
3. Zotero APIキーとZoteroユーザーIDを入力します（セットアップを参照）。任意の設定：ライブラリの種類と グループID（グループライブラリの場合）、Unpaywall用のメールアドレス（オープンアクセスPDFの検索）、および許可する削除操作 （デフォルト：なし。安全でない操作を参照）。

この拡張機能にはサーバーとすべての依存関係が含まれているため、npm installは不要です。Node.js 22以降が必要です （マニフェストのcompatibility.runtimes.node）。MCPBのドキュメントによると、Claude Desktopはアプリに同梱されているランタイムで Node.js拡張機能を実行します。APIキーは機密設定として宣言されており（マスクされた入力、クライアントによる安全な保存）、 拡張機能の設定で許可する削除操作を変更しない限り、削除は無効のままです。

この拡張機能に含まれるのはMCPサーバーのみです。skills/にあるClaudeスキル（サンドボックス内での引用の挿入、 科学的な文章作成）は、Claudeスキルのセットアップで説明されているとおり、 同じリリースの.zipファイルから別途インストールします。

手動設定（任意のMCPクライアント）

Claude Desktopの設定（または別のMCPクライアントの同等のファイル）に追加します。

{
  "mcpServers": {
    "zotero": {
      "command": "npx",
      "args": ["-y", "@xevos117/mcp-zotero"],
      "env": {
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "ZOTERO_USER_ID": "YOUR_USER_ID",
        "UNPAYWALL_EMAIL": "YOUR_EMAIL"
      }
    }
  }
}

Claude Codeとの統合

claude mcp add zotero -e ZOTERO_API_KEY=YOUR_API_KEY -e ZOTERO_USER_ID=YOUR_USER_ID -- npx -y @xevos117/mcp-zotero

必要に応じて-e UNPAYWALL_EMAIL=...または-e UNSAFE_OPERATIONS=itemsを追加し、すべてのプロジェクトでサーバーを 利用できるようにするには--scope userを指定します（デフォルトのlocalスコープでは現在のプロジェクトのみが対象です）。 このリポジトリをクローンした環境では、代わりにnpx tsx src/server.tsでソースからサーバーを実行できます （開発を参照）。

利用可能なツール

ライブラリの閲覧

ツール	説明
get_collections	すべてのコレクション（フォルダー）をキー、名前、親との関係とともに一覧表示します
get_collection_items	指定したコレクション内のアイテムを、キー、タイトル、著者、日付とともに取得します
search_library	クエリで検索するか、フィールド（日付、タイトルなど）で並べ替えたアイテムを一覧表示します
get_items_details	複数のアイテムのメタデータをまとめて取得します — アイテムタイプ固有のすべてのフィールド（bookTitle、proceedingsTitle、universityなど）、authors文字列、および構造化されたcreatorsを返します。ライブラリにないキーはnot_foundに一覧表示されます
get_item_fulltext	Zoteroの全文インデックスを介してPDF添付ファイルの全文を取得します

コンテンツの追加

ツール	説明
add_items_by_doi	DOIで論文を追加し、メタデータを自動解決します。Unpaywallを介してオープンアクセスPDFを自動添付します
add_items	メタデータを直接指定してアイテムを追加します — Zoteroの全37種類のアイテムタイプ（書籍、学位論文、レポートなど）に対応し、まとめて追加できます
create_collection	新しいコレクションを作成します。必要に応じて親の下にネストできます
import_pdf_to_zotero	URLからPDFをダウンロードし、Zoteroストレージにアップロードして、全文を自動でインデックス化します
find_and_attach_pdfs	Unpaywallを介してオープンアクセスPDFをまとめて検索し、自動添付します（アイテムキーまたはコレクションを指定）
add_linked_url_attachment	既存のアイテムにURLを添付するか、単独のリンクを作成します

コンテンツの削除

ツール	説明
delete_items	1回の呼び出しで最大50件のアイテムを完全に削除します（Zoteroのゴミ箱には移動されません）。UNSAFE_OPERATIONS=itemsまたはallが必要です
delete_collection	コレクション（フォルダー）を削除します。中のアイテムは保持されます。UNSAFE_OPERATIONS=allが必要です

引用と文書

ツール	説明
inject_citations	Word 文書に Zotero の最新の引用を挿入します。APA、IEEE、Vancouver、Harvard、Chicago に対応しています。出力は入力ファイルと同じフォルダーに _cited の接尾辞を付けて保存されます（例：paper.docx → paper_cited.docx）
get_user_id	設定済みの Zotero ユーザー ID を返します

開発

npm install
npm run build          # Compile TypeScript
npm test               # Unit and per-tool tests (vitest, fetch faked, ~1000 tests)
npm run test:e2e       # Built server over stdio against a local fake Zotero API
npm run smoke          # Quick stdio smoke test of the built server (user + group library)
npm run bundle         # Claude Desktop extension: dist/mcp-zotero.mcpb (production dependencies only)
npm run smoke -- --bundle dist/mcp-zotero.mcpb   # smoke test of the unpacked bundle, started from its manifest
npx tsx src/server.ts  # Run directly without building

テスト

レイヤー	コマンド	実行対象	テスト内容
単体／ツールごと	npm test	すべての PR（Node 22、24、26）	実際の MCP クライアントを通じてすべてのツールをテストします。fetch レベルで Zotero を模擬します。生成された .docx ファイルは公式 CSL スキーマに対して検証され、citeproc-js でレンダリングされます（test/helpers/docx-validate.ts）
E2E とスモーク	npm run test:e2e、npm run smoke	すべての PR	コンパイル済みサーバーを stdio 経由で実行し、ユーザーライブラリとグループライブラリをテストします
ライブ	npm run test:live（ワークフロー、エージェントのスモークテストと共有）	このリポジトリからの PR、main、毎週（金曜日）、手動実行	専用テストアカウントで実際の Zotero Web API をテストします（test/live）。ZOTERO_TEST_API_KEY が設定されていない場合はスキップされます
エージェントのスモークテスト	ワークフロー、ライブテストのスイートが合格した後	このリポジトリからの PR、手動実行（例：マージ後に main で実行）	Claude Code エージェントが、バージョン管理されたスキル .claude/skills/test-mcp-zotero に従い、ユーザーと同じようにサーバーを使用します。すべてのスタイルで inject_citations と inject.js の同等性を確認し、修正済みのエッジケースと、PR の変更内容に関する探索的なシナリオを最大 5 件テストします。ワークフローでは MCP サーバー、ツールセット、ガードフック（Bash の許可リスト、削除ポリシー、監査ログ）をセットアップします。ローカル実行でも同じ構成要素を使用します（test/live/agent/README.md）。判定はエージェントではなく test/live/verify-claims.mjs が行います。各実行でジョブの概要（判定、シナリオ、探索で見つかった内容、実行時の問題、ターン数／コスト／所要時間）を作成し、PR のコメントを常に最新の状態に保ちます。どちらもテストアカウントを特定できる情報は削除されます
Word	手動	リリースごと	test/WORD_CHECKLIST.md：Zotero プラグインを使って、引用を挿入した文書を Word で開きます

すべてのテストケースは test/TEST_CASES.md に記載されています。

ローカルでのライブテストでは ZOTERO_API_KEY は使用せず、ZOTERO_TEST_* 変数のみを使用します。

ZOTERO_TEST_API_KEY=... ZOTERO_TEST_USER_ID=... [email protected] npm run test:live

個人のライブラリに対して実行する場合は ZOTERO_LIVE_SAFE_MODE=1 を追加してください。テストスイートは mzt-<runId>… という名前のアイテムとコレクション、および mzt-run:<runId> タグのみを作成・削除し、コレクションの削除とグループへの書き込みはスキップします。専用テストアカウントは __mzt_disposable__ という名前のコレクションで識別されます。

依存関係は Claude Code エージェントによって毎月更新されます（ワークフロー、スキル .claude/skills/deps-update）。パッチのみの PR は、すべての必須チェックに合格すると自動マージされます。それ以外の PR はレビュー待ちとなります。GitHub Actions のバージョンは Dependabot によって更新されます。

CI の設定（リポジトリ所有者）

環境	シークレット	変数
zotero-live（ライブテスト、エージェントのスモークテスト）	ZOTERO_TEST_API_KEY、ZOTERO_TEST_USER_ID、ZOTERO_TEST_USERNAME、ZOTERO_TEST_GROUP_ID（任意）、UNPAYWALL_EMAIL	ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID、ANTHROPIC_WORKSPACE_ID
claude-deps（依存関係エージェント）	—	同じ4つのANTHROPIC_*変数（フェデレーションルールは異なっていてもかまいません）

エージェントは Anthropic Workload Identity Federation（GitHub OIDC、API キー不要）で Claude API に認証します。環境ごとにフェデレーションルールを1つ設定し、可能な限り範囲を絞ることをおすすめします。

ルールの対象	subject（完全一致、*なし）	claims（完全一致の文字列ペア）	condition（CEL）
zotero-live	repo:Xevos117/mcp-zotero:environment:zotero-live	repository_id: 1152178663、repository_owner_id: 86290818	claims.job_workflow_ref.startsWith("Xevos117/mcp-zotero/.github/workflows/claude-agent-smoke.yml@")（PR の実行では PR の ref が使われます）
claude-deps	repo:Xevos117/mcp-zotero:environment:claude-deps	repository_id: 1152178663、repository_owner_id: 86290818、job_workflow_ref: Xevos117/mcp-zotero/.github/workflows/deps-update.yml@refs/heads/main	—

Claims は完全一致の文字列ペアです（末尾に*を指定できるのはsubject_prefixのみ）。そのため、「任意の ref でこのワークフロー」を許可するには、上記のように CEL のconditionで指定する必要があります。完全一致のjob_workflow_ref（claude-deps、main のみ）は通常の claim として指定できます。

Audience は https://api.anthropic.com です。Subject は末尾が*でない限り完全一致します。環境を使用するジョブの OIDC subject は repo:Xevos117/mcp-zotero:environment:<environment> となるため、ブランチまたは PR の subject 用に記述されたルールとは一致しません。数値 ID（名前ではありません）を使うことで、名前が変更されたり、再作成されたりしたリポジトリやアカウントが一致するのを防げます。

zotero-liveでのトレードオフ：「任意の ref」の条件は、エージェントのスモークテストをプルリクエストで実行するために必要ですが、このリポジトリの任意のブランチにプッシュされたワークフローファイルの変更版も許可します（プッシュできるのは書き込み権限を持つ人のみです）。これを完全一致の claim job_workflow_ref: Xevos117/mcp-zotero/.github/workflows/claude-agent-smoke.yml@refs/heads/mainに固定すれば、この抜け道を塞げますが、PR でのエージェントのスモークテストは無効になります（その場合、mainからの手動実行でのみ実行されます）。

その他の所有者向け設定：

• Zotero のテストアカウントに__mzt_disposable__という名前のコレクションが必要です。
• リポジトリの設定：「Allow auto-merge」と「Allow GitHub Actions to create and approve pull requests」（依存関係ワークフローはGITHUB_TOKENを使って PR を作成します）。ルールセットでは、必須承認数を0件にしてください。依存関係の PR の自動マージにはこの設定が必要であり、2つ目の設定を許容できる理由にもなっています。この設定は、ワークフローによる PR の作成（必要）と承認（ここではどのワークフローも使用しません）を許可する、意図的なトレードオフです。承認が必須になった場合、ワークフローが自分の PR を承認できるようになるため、承認要件とあわせてこの設定を見直してください。
• いずれのワークフローも GitHub App を使用しません（エージェントは Workload Identity Federation で Anthropic に認証し、GitHub ではGITHUB_TOKENのみを使用します。エージェントは読み取り専用です）。Claude GitHub App がこのリポジトリにインストールされている場合は、アンインストールしてください。
• フェデレーションルールで使用する Anthropic ワークスペースに月間利用上限を設定してください。これはエージェントのコストに対する実質的な上限です。
• 残存リスク：OIDC トークンを保持するエージェントのスモークテストジョブは、PR のコードからビルドした MCP サーバーも実行します（これがテスト対象です）。このジョブは、所有者またはボットによる同一リポジトリ内の PR でのみ実行されます。トークンはzotero-live環境に紐づけられており、ワークスペースの利用上限によって不正利用のコストが制限されます。
• スタックのマージ後に必須となるチェック：test (node 22)、test (node 24)、test (node 26)、live-tests、agent-smoke。

リリース

1. CHANGELOG.md（Unreleased を新しいバージョンに移動）と、package.json のバージョン、server.json の version および packages[0].version、manifest.json のバージョンを更新します（異なる場合、npm test は失敗します）。
2. main で CI、ライブテスト、エージェントのスモークテストがすべて成功していることを確認します。
3. リリース候補によってドキュメントに挿入された内容を使って、手動の Word チェックリスト を実行し、結果をそのログに記録します。
4. Claude Desktop 拡張機能を含む最初のリリースの前（および manifest.json または Node.js の要件を変更するたび）に、npm run bundle でビルドし、実際の Claude Desktop（macOS または Windows）に dist/mcp-zotero.mcpb を一度インストールして、テストキーとユーザー ID を入力し、15 個のツールが表示され、get_collections が応答することを確認します。
5. GitHub リリースを公開します。リリースワークフロー はテストを実行し、npm に公開し、server.json を MCP レジストリ に公開して、スキルの ZIP ファイルと Claude Desktop 拡張機能（mcp-zotero.mcpb）を添付します。リリースタグにはバージョン（例：2.0.3）を指定する必要があります。レジストリジョブとバンドルジョブはタグをチェックアウトし、package.json のバージョンが異なる場合は失敗します。
6. mcp-registry ジョブだけが失敗した場合は、その実行で Re-run failed jobs を使用します。Re-run all jobs は npm の公開時点で停止します（そのバージョンはすでに存在するため）。そのため、レジストリの処理まで到達しません。

MCP Inspector でデバッグする

npx @modelcontextprotocol/inspector npx tsx src/server.ts

ライセンス

MIT - 詳細は LICENSE をご覧ください。