Zotero 用モデルコンテキストプロトコルサーバー

このプロジェクトは、 Zotero用のモデルコンテキストプロトコル（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 アシスタントはそれらを順番に使用してアイテムを検索し、そのメタデータまたはテキスト コンテンツを取得できます。

Related MCP server: Zotero MCP Server

インストール

このサーバーは、 Zoteroデスクトップアプリケーションが提供するローカルAPI 、またはZotero Web APIを介して実行できます。ローカルAPIはレスポンスが若干速くなりますが、APIが有効になっている同じコンピューター上でZoteroアプリが動作している必要があります。ローカルAPIを有効にするには、以下の手順を実行してください。

1. Zoteroを開き、「Zotero設定」を開きます

2. 「詳細設定」タブで、「このコンピューター上の他のアプリケーションが Zotero と通信できるようにする」というボックスにチェックを入れます。

[!重要] ライブラリ内のアイテムの全コンテンツを取得できるローカルAPIの/fulltextエンドポイントにアクセスするには、 Zoteroベータビルド（2025年3月30日時点）をインストールする必要があります。7.1がリリースされると、この状況は解消されます。詳しくはhttps://github.com/zotero/zotero/pull/5004をご覧ください。ベータビルドをインストールしたくない場合は、Web APIをご利用ください。

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

利用可能な構成オプションは次のとおりです。

• ZOTERO_LOCAL=true : ローカルの Zotero API を使用する (デフォルト: false、下記の注記を参照)

• ZOTERO_API_KEY : Zotero API キー (ローカル API では必要ありません)

• ZOTERO_LIBRARY_ID : Zotero ライブラリ ID (ユーザー ライブラリの場合はユーザー ID。ローカル API では必要ありません)

• ZOTERO_LIBRARY_TYPE : ライブラリの種類（ユーザーまたはグループ、デフォルト: ユーザー）

ローカル Zotero API を使用したuvx

これを Claude Desktop およびuvxを使用した直接の Python インストールで使用するには、 mcpServers構成に以下を追加します。

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

--updateフラグはオプションで、新しいバージョンが利用可能になった際に最新のバージョンをプルします。uvx がインストール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 syncを実行して、 uvで依存関係をインストールします。

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

Docker開発

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

docker build . -t zotero-mcp:local

MCP インスペクターを使用してコンテナをテストするには、次のコマンドを実行します。

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 で利用できます