Mendeley Mcp

Mendeley MCP サーバー

Mendeley の文献ライブラリを、Claude Desktop、Cursor、その他の MCP 対応クライアントなどの LLM アプリケーションに接続する MCP（Model Context Protocol） サーバーです。

特長

• ライブラリを検索 - タイトル、著者、要旨、メモで論文を検索します
• フォルダーを管理 - コレクションの閲覧、作成、名前変更、削除、階層化ができます
• 完全なメタデータを取得 - 要旨を含む文書の詳細情報をすべて取得します
• グローバルカタログを検索 - Mendeley の 1 億件以上の論文データベースにアクセスします
• DOI 検索 - DOI から論文を検索します
• 文書を管理 - フォルダー間で文献情報を追加、更新、削除、整理します
• 注釈を読む - PDF に付けたハイライトやメモを表示します
• BibTeX をエクスポート - 文書またはフォルダー全体の引用エントリを生成します
• 添付ファイルをダウンロード - Mendeley で公開されている文書ファイルを取得します

前提条件

1. Mendeley アカウント - mendeley.com で登録します（Elsevier 認証を使用します）
2. Mendeley API アプリ - dev.mendeley.com/myapps.html で登録します
   • Elsevier の認証情報でサインインします
   • 「Register a new app」をクリックします
   • リダイレクト URL に http://localhost:8585/callback を設定します
   • 「Authorization code」フローを選択します（Legacy ではありません）
   • Client ID と Client Secret を控えておきます

インストール

pip を使用

pip install mendeley-mcp

uv を使用（推奨）

uv tool install mendeley-mcp

Intel Mac の場合。 MCP SDK が依存関係として取り込む cryptography ライブラリは、バージョン 49 以降 macOS x86_64 向けのホイールの公開を停止しました。Intel Mac でツールチェーンを使わずにインストールできるよう、このパッケージでは cryptography を 49 未満に固定しています。この固定バージョンには、今後アップストリームのセキュリティ修正が提供されません。Apple Silicon、Linux、Windows には影響せず、最新リリースが使用されます。

Docker を使用

docker run -it \
  -e MENDELEY_CLIENT_ID="your-client-id" \
  -e MENDELEY_CLIENT_SECRET="your-client-secret" \
  -e MENDELEY_REFRESH_TOKEN="your-refresh-token" \
  ghcr.io/pallaprolus/mendeley-mcp

または、ローカルでビルドします：

git clone https://github.com/pallaprolus/mendeley-mcp.git
cd mendeley-mcp
docker build -t mendeley-mcp .

ソースから

git clone https://github.com/pallaprolus/mendeley-mcp.git
cd mendeley-mcp
pip install -e .

クイックスタート

1. Mendeley で認証する

認証ウィザードを実行します：

mendeley-auth login

次の処理が行われます：

1. Client ID と Client Secret の入力を求められます
2. アプリを認証するため、ブラウザーが開きます
3. 認証情報がシステムのキーリングに安全に保存されます

2. Claude Desktop に追加する

Claude Desktop の設定ファイルを編集します：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mendeley": {
      "command": "mendeley-mcp"
    }
  }
}

uv でインストールした場合：

{
  "mcpServers": {
    "mendeley": {
      "command": "uvx",
      "args": ["mendeley-mcp"]
    }
  }
}

3. Claude Desktop を再起動する

これで Claude から Mendeley のツールを利用できます。

利用可能なツール

ツール	説明
mendeley_search_library	ライブラリ内の文書を検索します
mendeley_get_document	特定の文書の詳細情報を取得します
mendeley_list_documents	文書を一覧表示します。フォルダーで絞り込むこともできます
mendeley_list_folders	すべてのフォルダー／コレクションを一覧表示します
mendeley_search_catalog	Mendeley の論文データベース全体を検索します
mendeley_get_by_doi	DOI で論文を検索します
mendeley_add_document	ライブラリに新しい文書を追加します
mendeley_update_document	既存の文書の書誌情報、タグ、キーワードを更新します
mendeley_delete_document	ライブラリから文書を完全に削除します
mendeley_create_folder	ライブラリにフォルダーを作成します。親フォルダーまたはグループの下に作成することもできます
mendeley_rename_folder	既存のフォルダーの名前を変更します
mendeley_delete_folder	既存のフォルダーを削除します
mendeley_add_document_to_folder	既存の文書を既存のフォルダーに追加します
mendeley_remove_document_from_folder	文書を削除せずにフォルダーから取り除きます
mendeley_get_annotations	文書に付けた PDF のハイライトとメモを取得します
mendeley_export_bibtex	文書またはフォルダーを BibTeX としてエクスポートします
mendeley_get_file_content	ライブラリまたはカタログの文書に最初に添付されたファイルをダウンロードします
mendeley_get_document_text	モデルが論文を読めるよう、文書に添付された PDF の全文を抽出します

リソース

上記のツールに加えて、サーバーは 2 つの MCP リソースを公開します。リソースは引数を取りません。リソースに対応したクライアントでは、サーバーとともにリソースが一覧表示され、ファイルを添付するのと同じように、会話のコンテキストとして添付できます。

リソース	内容
mendeley://library/recent	最近更新された 10 件の文書。同じ形式で mendeley_list_documents を使用します
mendeley://library/folders	ライブラリ内のすべてのフォルダーと、その id、name、parent_id

ツールリファレンス

mendeley_search_library

論文がユーザーのライブラリにすでに存在するはずの場合に使用します。

• タイトル、著者、要旨、メモを検索します
• 簡潔なメタデータ、書式設定済みの引用文、has_pdf を返します
• カタログを検索する前の最初の手順として最適です
• 最大 limit 件の結果を返します（デフォルトは 20 件）。必要に応じて Mendeley の検索結果をページごとに取得します

mendeley_get_document

ライブラリの document_id がすでに分かっている場合に使用します。

• 検索ツールより詳しいメタデータを返します
• 識別子、キーワード、タグ、タイムスタンプ、要旨、PDF の有無を含みます
• 既知の文書の確認、要約、後続の操作に最適です

mendeley_list_documents

キーワードで検索する代わりに、ライブラリを閲覧する場合に使用します。

• 特定の folder_id に結果を絞り込めます
• last_modified、created、title による並べ替えに対応しています
• 最大 limit 件の文書を返します（デフォルトは 50 件）。必要に応じてライブラリをページごとに取得するため、大きな limit を指定するとライブラリ全体が返されます
• 最近追加した文書や、特定のコレクションの内容を確認するのに便利です

mendeley_list_folders

フォルダーごとに文書を一覧表示する前に、コレクションの階層を把握するために使用します。

• フォルダーの ID と名前を返します
• 階層構造を再構築するための parent_id を含みます
• LLM がライブラリ構造を安全にたどる必要がある場合に便利です

mendeley_search_catalog

参照文献がユーザーのライブラリにない場合、またはより広く探索する場合に使用します。

• Mendeley のカタログ全体を検索します
• catalog_id、概要メタデータ、短縮された要旨を返します
• mendeley_search_library で一致する文書が見つからなかった場合のフォールバックとして適しています

mendeley_get_by_doi

DOI が分かっていて、フリーテキスト検索より確度の高い検索結果が必要な場合に使用します。

• Mendeley カタログで DOI を解決します
• catalog_id と、より詳細なカタログメタデータを返します
• mendeley_add_document または mendeley_get_file_content を実行する前に便利です

mendeley_add_document

すでに取得しているメタデータからライブラリエントリを作成する場合に使用します。

• 新しい Mendeley ライブラリレコードを作成します
• タイトル、著者、年、出典、要約、識別子を受け付けます
• PDF 自体はアップロードしません

mendeley_update_document

既存のライブラリエントリを修正または充実させる場合に使用します。

• 指定したフィールドのみを更新します（タイトル、種類、著者、年、出典、要約、識別子、タグ、キーワード）
• tags または keywords のリストを指定すると、既存のリストが置き換えられます。リストを空にするには [] を渡します。タグを追加するには、mendeley_get_document で現在のタグを読み取り、既存のタグと追加するタグを合わせたリストを渡します。Mendeley はタグをセットとして保存し、送信時の順序ではなく並べ替えて返します
• 更新後のドキュメントの状態を返します
• 誤った年の修正、欠けている要約の追加、識別子の修正、文献レビュー中の論文へのタグ付けなどに便利です

mendeley_delete_document

ドキュメントをライブラリから完全に削除する場合に使用します。

• 破壊的な操作であり、API から元に戻すことはできません
• ツールの説明では、最初にユーザーに確認するようモデルに指示しています

mendeley_remove_document_from_folder

ドキュメントをライブラリに残したまま、フォルダーから取り除く場合に使用します。

• mendeley_add_document_to_folder と組み合わせることで、ドキュメントをフォルダー間で移動できます
• ドキュメント自体は削除しません

mendeley_get_annotations

論文の PDF でユーザーがハイライトした箇所やメモを確認する場合に使用します。

• ユーザー自身の注釈（ハイライトと付箋メモ）を返します
• メモのテキスト、ハイライトの色、該当するページ番号が含まれます
• 論文のどこをユーザーが重要だと考えたかを示す、最も直接的な手がかりです

mendeley_export_bibtex

実際の参考文献形式で引用情報が必要な場合に使用します。

• 1 件のエントリには document_id、コレクション全体には folder_id を指定します
• BibTeX はローカルでテンプレートから生成するのではなく、Mendeley 自体が生成します
• .bib ファイルに貼り付けられる生のテキストを返します

mendeley_get_file_content

ライブラリドキュメントまたはカタログ検索結果について、Mendeley が公開する最初のファイルのダウンロードを試みる場合に使用します。

• ライブラリの document_id または catalog_id のいずれかを受け付けます
• 構造化メタデータと、利用可能な場合は埋め込み PDF リソースを返します
• ファイルが存在しない場合は、何も通知せず失敗するのではなく、ファイルがないことを明示して返します
• 著作権またはライセンス上の理由により、カタログ検索結果にはダウンロード可能な添付ファイルがないことがよくあります
• 10 MB を超えるファイルは、クライアントのコンテキストウィンドウを圧迫しないよう、報告のみ行い埋め込みません（MENDELEY_MCP_MAX_FILE_BYTES 環境変数で調整できます）
• 注：Claude Code を含むほとんどの MCP クライアントは、埋め込み PDF リソースを読み取り可能な内容にデコードしません。代わりに、生の base64 としてモデルに渡します。モデルに論文を実際に読ませるには、代わりに mendeley_get_document_text を使用してください。

mendeley_get_document_text

モデルに論文の内容を読ませたり、要約させたり、質問に答えさせたりする場合に使用します。

• ライブラリの document_id または catalog_id のいずれかを受け付けます
• 添付された PDF をダウンロードし、サーバー側でテキストを抽出して、読み取り可能なテキストブロックと、構造化結果の text フィールドに返します。構造化コンテンツのみを公開するクライアントも同じテキストを受け取ります（#11 を参照）。どちらの表現にも同じ切り捨て上限が適用され、互換性のためにレスポンスにはテキストが 2 回含まれます。
• 構造化結果には、どのような場合も message が含まれるため、ファイルがない場合、スキャンされた PDF の場合、エラーの場合の説明も、構造化データのみを扱うクライアントに表示されます。
• デジタル生成された PDF のみが対象です。スキャンされた PDF や画像のみの PDF にはテキストレイヤーがないため、その旨が報告されます（OCR が必要です）
• 出力は 200,000 文字までで、切り捨てが発生した場合は結果に示されます（MENDELEY_MCP_MAX_TEXT_CHARS 環境変数で調整できます）

使用例

設定が完了すると、Claude に次のような質問ができます。

• 「Mendeley ライブラリで transformer アーキテクチャに関する論文を検索して」
• 「『Machine Learning』フォルダーにはどの論文がありますか？」
• 「DOI 10.1038/nature14539 の論文を見つけて要約して」
• 「Mendeley カタログでタンパク質フォールディングに関する最近の論文を検索して」
• 「この論文をライブラリに追加して：［タイトル、著者など］」
• 「Mendeley ライブラリに『Systematic Review 2026』というフォルダーを作成して」
• 「フォルダー ID folder-123 の下に『Screening』というサブフォルダーを作成して」
• 「グループ group-456 に『Weekly Reading』というフォルダーを作成して」
• 「フォルダー folder-123 の名前を『Included Studies』に変更して」
• 「Mendeley ライブラリからフォルダー folder-999 を削除して」
• 「ドキュメント doc-789 をフォルダー folder-123 に追加して」
• 「ドキュメント doc-789 を『Screening』から『Included Studies』に移動して」
• 「doc-456 の年を修正して。2023 年ではなく、2024 年です」
• 「attention に関する論文では何にハイライトを付けましたか？」
• 「『Lit Review』フォルダーを BibTeX としてエクスポートして」
• 「タンパク質フォールディングに関する論文に添付された PDF をダウンロードして」

MCP クライアントまたはインスペクターでツールを直接呼び出す場合、フォルダー管理ツールでは次のような入力を受け付けます。

ルートフォルダーを作成する：

{
  "name": "Systematic Review 2026"
}

サブフォルダーを作成する：

{
  "name": "Screening",
  "parent_id": "folder-123"
}

フォルダーの名前を変更する：

{
  "folder_id": "folder-123",
  "name": "Included Studies"
}

フォルダーを削除する：

{
  "folder_id": "folder-999"
}

ドキュメントをフォルダーに追加する：

{
  "folder_id": "folder-123",
  "document_id": "doc-789"
}

ページを指定した PDF の読み取りと検索

mendeley_get_document_text は、オプションの page_start および page_end （1 始まり、指定ページを含む）を受け付けます。範囲を省略すると、PDF の最初または最後のページが選択されます。 既存の呼び出しでは引き続き全文が返されます。構造化された結果には、テキストのコピーを追加することなく、 page_number、start_offset、end_offset、truncated を含む範囲指定された pages エントリーも含まれます。オフセットは、返された text 内の 0 始まりの Python 文字位置です。終了オフセットは範囲に含まれません。 トリミングと 2 つの改行からなるページ区切りが考慮されます。出力上限によってページ全体が 省略された場合、そのページのオフセットはどちらも返されたテキストの末尾になり、 正規化されたテキスト内でその範囲が空でなければ（空白文字のみの場合を含む）、切り詰められたことが示されます。 全体のテキスト上限は、両方の互換表現に適用されます。ページ番号は PDF 内の位置を示し、 印刷されたページ番号ラベルを示すものではありません。選択したページが空白の場合、抽出可能なテキストがないことがあります。

0.7.0 から 0.8.0 への移行： pages[].text は削除されました。ページの返されたテキストは、トップレベルの text とそのオフセットから取得してください。

page_text = result["text"][page["start_offset"]:page["end_offset"]]

JavaScript／TypeScript の文字列インデックスは UTF-16 単位で数えますが、これらのオフセットは Unicode コードポイントで数え、BMP 外の各文字も 1 位置として扱います。次を使用してください。

const characters = Array.from(result.text); // Reuse for every page in this result.
const pageText = characters.slice(page.start_offset, page.end_offset).join("");

mendeley_search_document_text(document_id, query, limit=10, context_chars=200) は、読み取り出力の上限を超えるページも含め、すべての PDF ページからリテラルの大文字・小文字を区別しないフレーズを検索します。 ソースのメタデータ、ページ番号付きの抜粋、文字オフセット、total_matches、明示的な切り詰めフラグを返します。 limit は 1～100、context_chars は 0～2000 を受け付けます。一致判定には抽出されたテキストをそのまま使用するため、 PDF の改行をまたぐフレーズは一致しない場合があります。返される抜粋には常に一致箇所全体が含まれます。 まず前後のコンテキストが削減され、残りの上限にフレーズ全体を収められない場合は抜粋が省略されます。 一致の合計数には、省略された抜粋も含まれます。一致箇所と抜粋のオフセットは元の抽出ページテキストを参照し、 読み取り用のオフセットは返されたテキストを参照します。ダウンロードエラーと抽出エラーが発生した場合、 どちらのツールでもソースのメタデータは保持されます。どちらのツールも OCR やセマンティック検索は行いません。 選択されたページが空白の場合もありますが、PDF 全体で OCR が必要であることを示すものではありません。エラー結果には document_id、error_stage、file_available、text_available が含まれます。 file_available: null は、利用可能かどうかが判定されていないことを意味します。 出力上限には正のテキスト上限と 0 以上のファイル上限が必要です。0 を指定すると、 ファイルのメタデータは保持したままファイルの埋め込みが無効になります。無効な設定は起動時に拒否されます。これらの 上限は、PDF のダウンロードサイズや解析処理量を制限するものではありません。

例：「evaluation metrics」を検索し、一致する PDF ページを読み取ります。

フォルダー管理の検証

• mendeley_create_folder には空でない name が必要です。ネストして作成する場合は parent_id、グループに限定したフォルダーを作成する場合は group_id を任意で指定できます。
• mendeley_rename_folder には空でない folder_id と name が必要です。
• mendeley_delete_folder には空でない folder_id が必要です。
• mendeley_add_document_to_folder には空でない folder_id と document_id が必要です。
• 必須の文字列入力は、リクエストの送信前にトリミングされます。空または空白文字のみの必須値が指定された場合、書き込みを試みることなく JSON エラーレスポンスが返されます。
• 任意の parent_id と group_id の値は、指定された場合にトリミングされ、その後、追加のローカルビジネスルールを適用せずに上流へ転送されます。
• 名前の変更と削除の操作では、フォルダーが見つからない場合、アクセスエラー、またはコンテキストエラーが発生すると、誤った成功ペイロードではなく JSON エラーレスポンスが返されます。

mendeley_get_file_content には、ライブラリ内のドキュメント ID または catalog_id を指定できます。カタログのエントリーにはダウンロード可能なファイルがないことが多いため、ファイルが見つからない結果になる場合があります。

設定

環境変数

mendeley-auth login を使用しない場合は、環境変数で認証情報を設定できます。

# Required
export MENDELEY_CLIENT_ID="your-client-id"
export MENDELEY_CLIENT_SECRET="your-client-secret"

# One of the following (refresh token recommended - access tokens expire quickly)
export MENDELEY_REFRESH_TOKEN="your-refresh-token"
# OR
export MENDELEY_ACCESS_TOKEN="your-access-token"

任意の調整用変数：

# Max size of a file embedded by mendeley_get_file_content (default 10 MB)
export MENDELEY_MCP_MAX_FILE_BYTES="10485760"

# Max characters of extracted text returned by mendeley_get_document_text (default 200000)
export MENDELEY_MCP_MAX_TEXT_CHARS="200000"

または、MCP 設定で指定できます。

{
  "mcpServers": {
    "mendeley": {
      "command": "mendeley-mcp",
      "env": {
        "MENDELEY_CLIENT_ID": "your-client-id",
        "MENDELEY_CLIENT_SECRET": "your-client-secret",
        "MENDELEY_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

認証コマンド

# Check authentication status
mendeley-auth status

# Show environment variables for manual config
mendeley-auth show-env

# Remove saved credentials
mendeley-auth logout

更新された認証情報の保存

保存済みログインのアクセストークンの有効期限が切れると、サーバーはトークンを更新し、ログイン情報を保存した場所（システムのキーチェーン、または認証情報ファイル）に新しいトークンを書き戻します。認証情報ファイルは、プライベートな権限を設定してアトミックに置き換えられます。これにより、次回サーバーを起動したときには、トークン更新のための追加通信を行わずに有効なトークンを使用できます。

環境変数で指定された認証情報は、どこにも書き込まれません。この方法でデプロイする場合、トークンの永続性は利用者側で管理します。保存に失敗した場合、実行中のセッションでは更新後のトークンが保持され、認証情報の詳細を含まない警告がログに記録されます。次回起動時には、再度 mendeley-auth login が必要になることがあります。

開発

セットアップ

git clone https://github.com/pallaprolus/mendeley-mcp.git
cd mendeley-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

テスト

# Run tests
pytest

# Run with coverage
pytest --cov=mendeley_mcp

# Type checking
mypy src/mendeley_mcp

# Linting
ruff check src/

MCP Inspector でのテスト

# Install MCP inspector
npm install -g @modelcontextprotocol/inspector

# Run your server with inspector
npx @modelcontextprotocol/inspector mendeley-mcp

アーキテクチャ

┌─────────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  Claude Desktop │────▶│  mendeley-mcp    │────▶│   Mendeley API    │
│  (MCP Client)   │◀────│  (MCP Server)    │◀────│ api.mendeley.com  │
└─────────────────┘     └──────────────────┘     └───────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Local Keyring   │
                        │  (credentials)   │
                        └──────────────────┘

重要：このサーバーはお使いのマシン上でローカルに実行されます。認証情報やデータがサードパーティのサーバーを経由することはありません。すべての通信は、お使いのコンピューターと Mendeley の API の間で直接行われます。

認証情報の保存：キーチェーンが利用可能な場合、OAuth トークンとクライアントシークレットはシステム標準のキーチェーン（macOS Keychain、Windows Credential Locker、または Linux Secret Service）に保存され、クライアント ID のみが ~/.config/mendeley-mcp/credentials.json に保存されます。キーチェーンが利用できない場合は、認証情報がプライベートな権限を設定してそのファイルに保存されます。署名付きダウンロード URL のクエリは HTTPX のリクエストログから除外され、ダウンロードエラーメッセージにも含まれません。

レート制限

Mendeley API のレート制限はユーザーごとに適用されます。レート制限に達した場合：

• サーバーはトークンを自動的に更新します
• 数分待ってから再試行してください
• 頻繁に利用する場合は、リクエストを時間をかけて分散することを検討してください

トラブルシューティング

「認証情報が見つかりません」

mendeley-auth login を実行して認証してください。

「トークンの有効期限が切れました」

アクセストークンの有効期限が切れています。サーバーは更新トークンを使用して自動的にトークンを更新し、新しいトークンをキーチェーンまたは認証情報ファイルに保存します。これに失敗した場合は、再度 mendeley-auth login を実行してください。

「401 Unauthorized」

アプリの認証が解除された可能性があります。mendeley-auth login で再認証してください。

Claude にサーバーが表示されない

1. お使いの OS に合った設定ファイルのパスが正しいことを確認します
2. JSON が有効であることを確認します（末尾に余分なカンマがないこと）
3. Claude Desktop を完全に再起動します
4. Claude のログにエラーがないか確認します

貢献

貢献を歓迎します。以下の手順でお願いします。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. テストとリンティングを実行します
5. プルリクエストを送信します

ライセンス

MIT ライセンスです。詳しくは LICENSE ファイルをご覧ください。

免責事項

このプロジェクトは、Mendeley または Elsevier とは提携しておらず、承認や後援も受けていません。Mendeley は Elsevier B.V. の商標です。

謝辞

• Anthropic による Model Context Protocol
• MCP Python SDK
• Mendeley API のドキュメント

貢献者

• @roych98 — MCP SDK 2.x のインストール不具合を報告し、暫定的なバージョン固定を提供し、SDK v2 への移行を実施しました（#8）
• @im-alexandre — #2 を元に、フォルダー管理ツールを調整しました
• @Storkholm — 構造化コンテンツに関するクライアントの挙動を報告し、原因を特定しました（#11）
• @HasiVS — ドキュメント更新時のタグとキーワードを要望し（#12）、フォルダー一覧の切り詰めを報告しました（#13）