paperqa-mcp-server

paperqa-mcp-server

Claude が PDF ライブラリ全体を読み取り、検索し、内容を統合できるようにします。PaperQA2 を基盤としています。

Zotero の保存フォルダー（または任意の PDF フォルダー）を指定すれば、複数の論文を深く読み込む必要がある質問を Claude に尋ねられます。

クイックスタート

1. uv をインストールする

uv は Python パッケージマネージャーです。まだインストールしていない場合は、次の手順に従ってください。

curl -LsSf https://astral.sh/uv/install.sh | sh

インストール後、uv が PATH に追加されるように、ターミナルを再起動してください。

動作を確認します。

uv --version

2. OpenAI API キーを取得する

PaperQA2 は埋め込みと内部推論に OpenAI を使用します。https://platform.openai.com/api-keys でキーを取得してください。

3. パッケージキャッシュを準備する

初回実行時には約 90 個の Python パッケージがダウンロードされます。これは正常な動作で、発生するのは一度だけです。Claude Desktop がサーバーを起動する前にパッケージをキャッシュできるよう、次を実行してください。

uvx paperqa-mcp-server index 2>&1 | head -1

Building index: ... のような出力が表示されます。Ctrl+C を押して停止してください（実際のインデックス作成は手順 6 で実行します）。代わりに Python エラーが表示された場合は、インストールに問題があります。

4. uvx のフルパスを確認する

Claude Desktop は uvx を自動で見つけられないため、フルパスを指定する必要があります。次を実行してください。

which uvx

/Users/yourname/.local/bin/uvx のようなパスが表示されます。コピーしてください。次の手順で必要になります。

5. Claude Desktop に追加する

1. Claude Desktop を開きます
2. 設定 → 開発者 → 設定を編集に移動します
3. claude_desktop_config.json が開きます。mcpServers の中に paperqa エントリを追加します（mcpServers が存在しない場合は作成してください）。

{
  "mcpServers": {
    "paperqa": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["paperqa-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

次の 2 つのプレースホルダーを置き換えてください。

• /Users/yourname/.local/bin/uvx — 手順 4 で which uvx を実行したときの出力を貼り付けます
• sk-your-key-here — 手順 2 で取得した OpenAI API キーを指定します

PDF が ~/Zotero/storage 以外の場所にある場合は、env に PAPER_DIRECTORY エントリを追加してください。

"env": {
  "OPENAI_API_KEY": "sk-your-key-here",
  "PAPER_DIRECTORY": "/full/path/to/your/pdfs"
}

4. Claude Desktop を完全に終了し（ウィンドウを閉じるだけでなく、Cmd+Q を押します）、再起動します
5. ハンマーアイコンが表示されます。クリックして、paper_qa が一覧にあることを確認してください

6. インデックスを事前に作成する

Claude が論文を検索する前に、サーバーで検索インデックスを作成する必要があります。各 PDF を読み取り、チャンクに分割して、OpenAI の埋め込み API に送信します。数百件の論文がある場合は時間がかかり、API 呼び出しに数ドルの費用がかかります。

インデックス未作成の論文が 10 件を超える場合、サーバーはクエリへの応答を拒否し、先にこの手順を実行するよう通知します。新しい論文が数件の場合は、クエリ時に自動でインデックスが作成されます。

export OPENAI_API_KEY=sk-your-key-here
uvx paperqa-mcp-server index

各論文の処理中にログが表示されます。完了すると、Done. と出力されます。

この処理がレート制限エラーでクラッシュした場合は、同じコマンドをもう一度実行してください。前回の続きから再開し、実行するたびにインデックス対象のファイルが増えます。大規模なライブラリ（論文 500 件以上）では、何度か実行する必要がある場合があります。

その後、インデックスは ~/.pqa/indexes/ にキャッシュされます。以降の実行では、新規ファイルまたは変更されたファイルのみが再処理されます。

トラブルシューティング

Claude Desktop に「Server disconnected」と表示される

Claude Desktop の起動タイムアウトは短く設定されています。初回起動時に uv がパッケージをダウンロードする必要がある場合、タイムアウトになります。解決方法：ターミナルから uvx paperqa-mcp-server を一度実行して、パッケージをキャッシュしてください。

クエリ時に「Index incomplete」と表示される

サーバーは各クエリの前にインデックスを確認します。インデックス未作成の論文が多すぎる場合、その場で一括インデックス作成を試みて失敗する代わりに、診断メッセージを返します。解決方法：手順 6 のインデックス作成コマンドを実行してください。

ハンマーアイコンが表示されない

Claude Desktop を完全に終了（Cmd+Q）してから再起動したことを確認してください。claude_desktop_config.json に JSON 構文エラーがないか確認してください。最もよくある間違いは、カンマの入れ忘れです。

別の LLM を使用する

デフォルトでは、PaperQA2 は内部推論に gpt-4o-mini を使用します。これは Claude とは別のものです。Claude がツールを呼び出し、PaperQA2 はエビデンスの収集と統合のために、内部で独自に LLM を呼び出します。

別のモデルを使用するには、Claude Desktop の設定に環境変数を追加してください。

"env": {
  "OPENAI_API_KEY": "sk-your-key-here",
  "PQA_LLM": "gpt-4o",
  "PQA_SUMMARY_LLM": "gpt-4o-mini"
}

すべての環境変数

変数	デフォルト	用途
PAPER_DIRECTORY	~/Zotero/storage	PDF を格納するフォルダー
OPENAI_API_KEY	—	デフォルトの埋め込みに必須です
PQA_LLM	gpt-4o-mini	内部推論に使用する LLM
PQA_SUMMARY_LLM	gpt-4o-mini	チャンクの要約に使用する LLM
PQA_EMBEDDING	text-embedding-3-small	埋め込みモデル
ANTHROPIC_API_KEY	—	Claude を内部 LLM として使用する場合のみ

zotero-mcp との連携

zotero-mcp と組み合わせると便利です。

• paperqa-mcp-server — 論文の全文を対象とした詳細な読解と統合
• zotero-mcp — ライブラリの閲覧、メタデータの検索、注釈の読み取り

Claude はこれらを相互参照できます。たとえば、PaperQA で論文を探してから、その Zotero のメタデータや注釈を取得できます。 PaperQA2 の引用には Zotero のストレージキー（例：storage/ABC123DE/paper.pdf の ABC123DE）が含まれており、Claude はこれを使って zotero-mcp 経由でアイテムを検索できます。

インデックス実装に関する注意事項

paperqa-mcp-server index は MCP サーバーと同じ _settings() 関数を使用するため、構築されるインデックスはサーバーが検索するインデックスと完全に一致します。PaperQA2 のインデックスディレクトリ名は、設定（埋め込みモデル、チャンクサイズ、論文ディレクトリのパスなど）のハッシュです。設定には次の内容が含まれます。

• マルチモーダル OFF — PDF からの画像抽出をスキップします（CMYK 画像を含む PDF でのクラッシュを回避します）。
• ドキュメント詳細 OFF — Crossref／Semantic Scholar のメタデータ検索をスキップします（レート制限を回避します。Claude は zotero-mcp 経由で Zotero から直接メタデータを取得できます）。
• 同時実行数 1 — OpenAI の埋め込みレート制限を超えないよう、ファイルを一度に 1 つずつインデックス化します。

pqa index を使わない理由 pqa CLI は pydantic の CliSettingsSource を介して設定を構築するため、Python で直接 Settings() を構築した場合とはデフォルト値が異なります（例：chunk_chars が 7000 ではなく 5000）。設定が異なるとインデックスのハッシュも異なり、サーバーがインデックスを見つけられません。インデックスの構築には、必ず paperqa-mcp-server index を使用してください。

GitHub から最新バージョンをインストール

PyPI ではなく、main ブランチの最新バージョンを使用するには：

{
  "mcpServers": {
    "paperqa": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/menyoung/paperqa-mcp-server", "paperqa-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

最新の main ブランチからインデックスを構築するには：

OPENAI_API_KEY=sk-your-key-here uvx --from git+https://github.com/menyoung/paperqa-mcp-server paperqa-mcp-server index

開発

サーバーに貢献する場合、またはローカルで変更する場合：

git clone https://github.com/menyoung/paperqa-mcp-server.git
cd paperqa-mcp-server
uv sync
uv run paperqa-mcp-server        # run the server
uv run paperqa-mcp-server index  # build the index