Unpaywall MCP

🚀 Unpaywall MCP Server

Unpaywallのツールを公開するMCP（Model Context Protocol）サーバーで、AIクライアントは以下のことができます。

• DOIでメタデータを取得する
• 記事のタイトルを検索する
• 最適なOAの全文リンクを取得する
• OAのPDFをダウンロードしてテキストを抽出する

🚀 クイックスタート

npxを使用する場合

これをMCPクライアントの設定に追加してください（Claude Desktopの例）。

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": { "UNPAYWALL_EMAIL": "you@example.com" }
    }
  }
}

その後、ツールを試してみてください。unpaywall_search_titles、unpaywall_get_fulltext_links、unpaywall_fetch_pdf_text などが利用できます。

✨ 必要条件

• Node.js 18以上
• Unpaywallへのリクエストに使用するメールアドレス（礼儀正しい利用のために必要です）。

📦 インストール

通常のセットアップ

# 依存関係のインストール
npm install

# ビルド
npm run build

# 実行（MCPクライアントが必要とするstdioトランスポートで）
UNPAYWALL_EMAIL=you@example.com npm start

開発時のホットラン（ビルドステップ不要）

UNPAYWALL_EMAIL=you@example.com npm run dev

💻 使用例

ツールの説明

unpaywall_get_by_doi

• 説明: DOIに対するUnpaywallのメタデータを取得する
• 入力スキーマ:
  • doi（文字列、必須）: 例 10.1038/nphys1170
  • email（文字列、オプション）: 指定された場合、UNPAYWALL_EMAIL を上書きする
• 出力: UnpaywallからのJSONレスポンス

unpaywall_search_titles

• 説明: クエリに一致する記事のタイトルをUnpaywallで検索する（1ページあたり50件の結果）
• 入力スキーマ:
  • query（文字列、必須）: タイトルのクエリ
  • is_oa（ブール値、オプション）: trueの場合、OAの結果のみ；falseの場合、閉じたアクセスの結果のみ；省略するとすべての結果
  • page（整数、1以上、オプション）: ページ番号
  • email（文字列、オプション）: UNPAYWALL_EMAIL を上書きする
• 出力: GET https://api.unpaywall.org/v2/search からのJSON検索結果

unpaywall_get_fulltext_links

• 説明: DOIに対する最適なOAのPDF URLとOpen URL、およびすべてのOAの場所を返す
• 入力スキーマ:
  • doi（文字列、必須）
  • email（文字列、オプション）: UNPAYWALL_EMAIL を上書きする
• 出力: best_pdf_url、best_open_url、best_oa_location、oa_locations および選択されたメタデータを含むJSON

unpaywall_fetch_pdf_text

• 説明: DOIに対する最適なOAのPDFからテキストをダウンロードして抽出する、または提供された pdf_url から抽出する
• 入力スキーマ:
  • pdf_url（文字列、オプション）: 直接のPDF URL（優先される）
  • doi（文字列、オプション）: pdf_url が提供されない場合、最適なOAのPDFを解決するために使用される
  • email（文字列、オプション）: doi を使用し、UNPAYWALL_EMAIL 環境変数が設定されていない場合に必要
  • truncate_chars（整数、1000以上、オプション）: 抽出されたテキストの最大文字数を返す（デフォルトは20000）
• 出力: text（場合によっては切り捨てられる）、length_chars、truncated、pdf_url およびPDFのメタデータを含むJSON

LLMへのプロンプトのヒント（MCP）

MCP対応のLLMクライアントからこのサーバーを使用する場合、モデルに以下のことを依頼してください。

• 検索してから取得する: unpaywall_search_titles を簡潔なタイトルフレーズで使用し、結果を選択してから、選択したDOIに対して unpaywall_get_fulltext_links または unpaywall_fetch_pdf_text を呼び出します。
• OAを優先する: オープンアクセスのみが必要な場合は、検索で is_oa: true を渡します。
• サイズを制御する: unpaywall_fetch_pdf_text で truncate_chars を設定し（デフォルトは20000）、長いテキストを要約してから処理を続けます。
• 回復力を持つ: 最適なPDF URLがない場合は、best_open_url にフォールバックし、ランディングページからコンテンツを抽出します（このサーバーの外で）。
• レート制限を尊重する: 多くの呼び出しを行う場合は、リクエストを間隔をあけて行い、同じ呼び出しを繰り返す代わりに以前のレスポンスを再利用します。

LLMへの良いユーザー指示の例:

• "「生物医学における基礎モデル」に関する3つのOA論文を見つけ、最良の論文の序章を抽出して要約してください。"
• "「2024年のグラフニューラルネットワークの調査」を検索し、可能であればOAにフィルタリングしてから、PDFのテキストを取得して10項目の要約を作成してください。"

ツール呼び出しのペイロードの例

MCPクライアントによって構造は異なりますが、核心的なペイロードは次の通りです。

// タイトルを検索する
{
  "name": "unpaywall_search_titles",
  "arguments": {
    "query": "graph neural networks survey",
    "is_oa": true,
    "page": 1
  }
}

// DOIに対する最適なOAのリンクを取得する
{
  "name": "unpaywall_get_fulltext_links",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434"
  }
}

// PDFのテキストを取得して抽出する（DOIによる）
{
  "name": "unpaywall_fetch_pdf_text",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434",
    "truncate_chars": 20000
  }
}

MCPクライアントでの設定

Claude Desktopでの推奨（ビルド不要）設定（npm/npxを使用）:

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

コンパイルされたdistを使用する代替（ローカルリポジトリ）設定:

{
  "mcpServers": {
    "unpaywall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

追加した後、クライアントにツールをリスト表示させて試してみてください。

• query を指定した unpaywall_search_titles
• doi を指定した unpaywall_get_fulltext_links
• doi（または pdf_url）を指定した unpaywall_fetch_pdf_text

📚 その他の注意事項

• Unpaywallのレート制限と利用ガイドラインを尊重してください: https://unpaywall.org/products/api
• サーバーはstdioトランスポートと @modelcontextprotocol/sdk を使用しています。
• UNPAYWALL_EMAIL を設定するか、各呼び出しで email を渡して、Unpaywallが利用に関してあなたに連絡できるようにしてください。

🔧 メンテナー向け: npmへの公開

# 1) プロジェクトをビルドする（公開時にも自動的に実行されます）
npm run build

# 2) バージョンを上げる（patch/minor/majorを選択）
npm version patch

# 3) 公開する（ログインしていることを確認: npm login）
npm publish --access public

# 4) GitHubでリリースをタグ付けする（オプションですが、推奨）

ユーザーは、上記のように npx -y unpaywall-mcp でMCPクライアントを設定できます。クローンやビルドは必要ありません。