Model Context Protocol server for Zotero

Zotero 用 Model Context Protocol サーバー

このプロジェクトは、Zotero 用に Model Context Protocol (MCP) を実装した Python サーバーです。AI アシスタントから Zotero ライブラリにアクセスできるようにします。MCP クライアントでの利用を目的に、Zotero と連携する機能を絞り込みつつ、最大限に役立つものを実装しています。

機能

この MCP サーバーは、次のツールを提供します。

• zotero_search_items：テキストクエリを使って Zotero ライブラリ内のアイテムを検索します
• zotero_item_metadata：特定の Zotero アイテムについて、入力されているすべてのフィールドを出版情報、識別子、タイムスタンプ、ライブラリ情報に分類した完全なメタデータを取得します
• zotero_item_fulltext：特定の Zotero アイテムの全文（PDF の内容など）を取得します

これらのツールは、任意の MCP クライアント、または MCP Inspector から検出して利用できます。

各ツールは、Zotero アイテムから関連情報を含む整形済みテキストを返します。Claude などの AI アシスタントは、まずアイテムを検索し、続いてそのメタデータやテキストコンテンツを取得するという順序でツールを使用できます。

インストール

このサーバーは、Zotero デスクトップアプリが提供するローカル API)、または Zotero Web API を使用して実行できます。ローカル API のほうが応答性に優れる場合がありますが、同じコンピューターで Zotero アプリを起動し、API を有効にしておく必要があります。ローカル API を有効にするには、次の手順を実行します。

1. Zotero を開き、「Zotero Settings」を開きます
2. 「Advanced」タブで、「Allow other applications on this computer to communicate with Zotero」という項目にチェックを入れます。

Zotero Web API を使用するには、API キーを作成し、Zotero アカウント設定の https://www.zotero.org/settings/keys でライブラリ ID（通常はユーザー ID）を確認する必要があります。

設定できる項目は次のとおりです。

• ZOTERO_LOCAL=true：ローカル Zotero API を使用します（デフォルト：false。下記の注記を参照）
• ZOTERO_API_KEY：Zotero API キー（ローカル API では不要）
• ZOTERO_LIBRARY_ID：Zotero ライブラリ ID（ユーザーライブラリの場合はユーザー ID。ローカル API では不要）
• ZOTERO_LIBRARY_TYPE：ライブラリの種類（user または group、デフォルト：user）

uvx とローカル Zotero API

Claude Desktop と uvx を使った直接的な Python インストールで利用するには、mcpServers の設定に次の内容を追加します。

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp@latest"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}

@latest の指定は任意です。指定すると、新しいバージョンが利用可能になったときに最新バージョンを取得します。uvx がインストールされていない場合は、代わりに pipx run を使用するか、このリポジトリをローカルにクローンして、下記の開発の手順に従ってください。

Zotero Web API を使った Docker

この MCP サーバーを Docker コンテナで実行する場合は、次の設定を使用し、API キーとライブラリ ID を入力してください。

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER",
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
        "ghcr.io/kujenga/zotero-mcp:main"
      ],
    }
  }
}

新しいバージョンに更新するには、docker pull ghcr.io/kujenga/zotero-mcp:main を実行します。Docker を使ったインストールでローカル Zotero API に接続することもできますが、その場合は Zotero アプリのローカル API インターフェースへのネットワーク接続を確保するため、上記のコマンドを変更する必要があります。

開発

プロジェクトへの変更やコントリビューションに関する情報です。

1. このリポジトリをクローンします
2. 次のコマンドを実行し、uv で依存関係をインストールします：uv sync
3. プロジェクトのルートに .env ファイルを作成し、上記の環境変数を設定します

ローカル開発用に MCP Inspector を起動します：

npx @modelcontextprotocol/inspector uv run zotero-mcp

ローカルリポジトリを Claude Desktop でテストするには、このディレクトリ内のシェルで echo $PWD/.venv/bin/zotero-mcp を実行し、Claude Desktop の設定に次の内容を設定します

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp"
      "env": {
        // Whatever configuration is desired.
      }
    }
  }
}

テストの実行

テストスイートを実行するには：

uv run pytest

リリース

1. pyproject.toml と server.json のバージョンを更新します（server.json では、サーバーのバージョンとパッケージのバージョンの2か所を更新します）。
2. make publish で PyPI に公開します。
3. 公式 MCP レジストリに更新したメタデータを公開します。必要に応じて、まず mcp-publisher login github で認証し、その後 make publish-mcp を実行します。

Docker 開発

次のコマンドでコンテナイメージをビルドします：

docker build . -t zotero-mcp:local

MCP Inspector でコンテナをテストするには、次のコマンドを実行します：

npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local

関連ドキュメント

• https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
• https://github.com/modelcontextprotocol/python-sdk
• https://pyzotero.readthedocs.io/en/latest/
• https://www.zotero.org/support/dev/web_api/v3/start
• https://modelcontextprotocol.io/llms-full.txt は LLM で利用できます

付録：Zotero の API に関するメモ

アイテムのメタデータは、固定リストではなく API が返すフィールドに基づいて表示されます。API が返さないフィールドは省略され、このサーバーが認識しないフィールドは「Other Fields」という見出しの下に表示されるため、Zotero をアップグレードしてもメタデータが気付かないうちに失われることはありません。

知っておくべき点として、2つの API には違いがあります。ローカル API のクイック検索では引用キーがインデックス化されますが、Web API ではインデックス化されません。そのため、引用キーのフィールドがデータに含まれていても、Web API で検索すると何も返されません。