mendeley-mcp

Mendeley MCP Server

An MCP (Model Context Protocol) server that connects your Mendeley reference library to LLM applications like Claude Desktop, Cursor, and other MCP-compatible clients.

Features

• Search your library - Find papers by title, author, abstract, or notes
• Manage folders - Browse, create, rename, delete, and nest collections
• Get full metadata - Retrieve complete document details including abstracts
• Search global catalog - Access Mendeley's 100M+ paper database
• DOI lookup - Find papers by their DOI
• Manage documents - Add, update, delete, and organize entries across folders
• Read your annotations - Surface the highlights and notes you made on PDFs
• Export BibTeX - Generate citation entries for a document or a whole folder
• Download attached files - Retrieve document files when Mendeley exposes them

Prerequisites

1. Mendeley Account - Sign up at mendeley.com (uses Elsevier authentication)
2. Mendeley API App - Register at dev.mendeley.com/myapps.html
   • Sign in with your Elsevier credentials
   • Click "Register a new app"
   • Set redirect URL to http://localhost:8585/callback
   • Select "Authorization code" flow (not Legacy)
   • Note your Client ID and Client Secret

Installation

Using pip

pip install mendeley-mcp

Using uv (recommended)

uv tool install mendeley-mcp

Intel Macs. The cryptography library, pulled in by the MCP SDK, stopped publishing macOS x86_64 wheels at version 49. On Intel Macs this package pins cryptography below 49 so installation works without a Rust toolchain. That pinned version no longer receives upstream security fixes; Apple Silicon, Linux, and Windows are unaffected and get the latest release.

Using 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

Or build locally:

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

From source

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

Quick Start

1. Authenticate with Mendeley

Run the authentication wizard:

mendeley-auth login

This will:

1. Prompt for your Client ID and Client Secret
2. Open your browser to authorize the app
3. Save your credentials securely in your system keyring

2. Add to Claude Desktop

Edit your Claude Desktop config file:

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"
    }
  }
}

If installed with uv:

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

3. Restart Claude Desktop

The Mendeley tools should now be available in Claude.

Available Tools

Tool	Description
mendeley_search_library	Search documents in your library
mendeley_get_document	Get full details of a specific document
mendeley_list_documents	List documents, optionally filtered by folder
mendeley_list_folders	List all folders/collections
mendeley_search_catalog	Search Mendeley's global paper database
mendeley_get_by_doi	Look up a paper by DOI
mendeley_add_document	Add a new document to your library
mendeley_update_document	Update bibliographic fields, tags, or keywords on an existing document
mendeley_delete_document	Permanently delete a document from your library
mendeley_create_folder	Create a folder in your library, optionally under a parent folder or group
mendeley_rename_folder	Rename an existing folder
mendeley_delete_folder	Delete an existing folder
mendeley_add_document_to_folder	Add an existing document to an existing folder
mendeley_remove_document_from_folder	Remove a document from a folder without deleting it
mendeley_get_annotations	Get your PDF highlights and notes on a document
mendeley_export_bibtex	Export a document or folder as BibTeX
mendeley_get_file_content	Download the first attached file for a library or catalog document
mendeley_get_document_text	Extract the full text of a document's attached PDF so the model can read the paper

Resources

Besides the tools above, the server exposes two MCP resources. Resources take no arguments; a client that supports them lists them alongside the server and lets you attach one to a conversation as context, the way you would attach a file.

Resource	Contents
mendeley://library/recent	The 10 most recently modified documents, in the same format as mendeley_list_documents
mendeley://library/folders	Every folder in the library with its id, name, and parent_id

Tool Reference

mendeley_search_library

Use this when the paper should already exist in the user's library.

• Searches title, authors, abstract, and notes
• Returns concise metadata, formatted citation text, and has_pdf
• Best first step before falling back to the catalog
• Returns up to limit results (default 20), paging through Mendeley's results as needed

mendeley_get_document

Use this after you already know the library document_id.

• Returns fuller metadata than the search tool
• Includes identifiers, keywords, tags, timestamps, abstract, and PDF presence
• Best for inspection, summarization, and follow-up actions on a known document

mendeley_list_documents

Use this to browse the library instead of searching by keyword.

• Can scope results to a specific folder_id
• Supports sorting by last_modified, created, or title
• Returns up to limit documents (default 50), paging through the library as needed, so a large limit returns the whole library
• Useful for reviewing recent additions or the contents of one collection

mendeley_list_folders

Use this to understand the collection hierarchy before listing documents by folder.

• Returns folder IDs and names
• Includes parent_id to reconstruct nesting
• Useful when an LLM needs to navigate a library structure safely

mendeley_search_catalog

Use this when the reference is not in the user's library or when you want broader discovery.

• Searches Mendeley's global catalog
• Returns catalog_id, summary metadata, and truncated abstract text
• Good fallback when mendeley_search_library does not find a match

mendeley_get_by_doi

Use this when a DOI is known and you want a higher-confidence lookup than free-text search.

• Resolves the DOI in the Mendeley catalog
• Returns catalog_id plus richer catalog metadata
• Useful before mendeley_add_document or mendeley_get_file_content

mendeley_add_document

Use this to create a library entry from metadata you already have.

• Creates a new Mendeley library record
• Accepts title, authors, year, source, abstract, and identifiers
• Does not upload a PDF by itself

mendeley_update_document

Use this to fix or enrich an existing library entry.

• Updates only the fields you supply (title, type, authors, year, source, abstract, identifiers, tags, keywords)
• A supplied tags or keywords list replaces the existing list; pass [] to clear it. To add a tag, read the current tags with mendeley_get_document and pass the combined list. Mendeley stores tags as a set and returns them sorted, not in the order sent
• Returns the document's state after the update
• Useful for correcting a wrong year, adding a missing abstract, fixing identifiers, or tagging papers during a literature review

mendeley_delete_document

Use this to permanently remove a document from the library.

• Destructive and not reversible through the API
• The tool description instructs the model to confirm with the user first

mendeley_remove_document_from_folder

Use this to take a document out of a folder while keeping it in the library.

• Complements mendeley_add_document_to_folder — together they let you move documents between folders
• Does not delete the document itself

mendeley_get_annotations

Use this to see what the user highlighted or noted in a paper's PDF.

• Returns the user's own annotations: highlights and sticky notes
• Includes note text, highlight color, and the page numbers involved
• The most direct signal of what the user found important in a paper

mendeley_export_bibtex

Use this when the user needs citations in a real reference format.

• Provide document_id for one entry or folder_id for a whole collection
• BibTeX is generated by Mendeley itself, not templated locally
• Returns raw text ready to paste into a .bib file

mendeley_get_file_content

Use this to try downloading the first file Mendeley exposes for a library document or catalog hit.

• Accepts either a library document_id or a catalog_id
• Returns structured metadata and an embedded PDF resource when available
• If no file exists, returns a clear no-file result instead of failing silently
• Catalog results often have no downloadable attachment for copyright or licensing reasons
• Files larger than 10 MB are reported but not embedded, to avoid flooding the client's context window (adjust with the MENDELEY_MCP_MAX_FILE_BYTES environment variable)
• Note: most MCP clients (including Claude Code) do not decode the embedded PDF resource into readable content — they pass it to the model as raw base64. To have the model actually read a paper, use mendeley_get_document_text instead.

mendeley_get_document_text

Use this when the user wants the model to read, summarize, or answer questions about a paper's contents.

• Accepts either a library document_id or a catalog_id
• Downloads the attached PDF and extracts its text server-side, returning it as a readable text block and in the structured result's text field. Clients that expose only structured content receive the same text (see #11). Both representations use the same truncation limit; the response carries the text twice for compatibility.
• The structured result includes a message on every path, so explanations for missing files, scanned PDFs, and errors remain visible to structured-only clients.
• Born-digital PDFs only; scanned or image-only PDFs have no text layer and are reported as such (they would need OCR)
• Output is capped at 200,000 characters, with truncation flagged in the result (adjust with the MENDELEY_MCP_MAX_TEXT_CHARS environment variable)

Example Usage

Once configured, you can ask Claude things like:

• "Search my Mendeley library for papers about transformer architectures"
• "What papers do I have in my 'Machine Learning' folder?"
• "Find the paper with DOI 10.1038/nature14539 and summarize it"
• "Search the Mendeley catalog for recent papers on protein folding"
• "Add this paper to my library: [title, authors, etc.]"
• "Create a folder called 'Systematic Review 2026' in my Mendeley library"
• "Create a subfolder called 'Screening' under folder ID folder-123"
• "Create a folder called 'Weekly Reading' in group group-456"
• "Rename folder folder-123 to 'Included Studies'"
• "Delete folder folder-999 from my Mendeley library"
• "Add document doc-789 to folder folder-123"
• "Move document doc-789 from 'Screening' to 'Included Studies'"
• "Fix the year on doc-456 — it should be 2024, not 2023"
• "What did I highlight in the attention paper?"
• "Export my 'Lit Review' folder as BibTeX"
• "Download the PDF attached to the paper about protein folding"

For direct tool calls in an MCP client or inspector, the folder-management tools accept inputs like:

Create a root folder:

{
  "name": "Systematic Review 2026"
}

Create a subfolder:

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

Rename a folder:

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

Delete a folder:

{
  "folder_id": "folder-999"
}

Add a document to a folder:

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

Page-aware PDF reading and search

mendeley_get_document_text accepts optional page_start and page_end (1-based, inclusive). Omitted bounds select the first or last PDF page. Existing calls still return full text; structured results also include bounded pages entries with page_number, start_offset, end_offset, and truncated, without another copy of the text. Offsets are zero-based Python character positions in the returned text; the end offset is exclusive. They account for trimming and the two-newline page separators. A page fully omitted by the output cap has both offsets at the end of the returned text and is flagged as truncated when its span in the canonical text was non-empty, including whitespace. The overall text limit applies to both compatibility representations. Page numbers refer to PDF positions, not printed page labels. Blank selected pages can have no extractable text.

Migration from 0.7.0 to 0.8.0: pages[].text is removed. Obtain a page's returned text from the top-level text and its offsets:

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

JavaScript/TypeScript string indices count UTF-16 units; these offsets count Unicode code points, including each non-BMP character as one position. Use:

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) searches every PDF page for a literal, case-insensitive phrase, including pages beyond the reading output limit. It returns source metadata, page-numbered passages, character offsets, total_matches, and explicit truncation flags. limit accepts 1–100; context_chars accepts 0–2000. Matching uses extracted text as-is, so phrases split across PDF line breaks may not match. Returned passages always contain the complete match: context is reduced first, and a passage is omitted if the remaining budget cannot hold the phrase. Total match counts still include omitted passages. Match and passage offsets index the original extracted page text, while reading offsets index the returned text. Download and extraction errors retain source metadata in both tools. Neither tool performs OCR or semantic search. Empty selected pages may be blank; they do not establish that the whole PDF requires OCR. Error results include document_id, error_stage, file_available, and text_available; file_available: null means availability was not determined. Output limits require a positive text limit and a file limit of zero or greater; zero disables file embedding while preserving file metadata. Invalid configuration is rejected at startup. These limits do not bound PDF download size or parsing work.

Example: search for "evaluation metrics", then read the matching PDF pages.

Folder Management Validation

• mendeley_create_folder requires a non-empty name. You can optionally provide parent_id for nested creation or group_id for a group-scoped folder.
• mendeley_rename_folder requires non-empty folder_id and name.
• mendeley_delete_folder requires a non-empty folder_id.
• mendeley_add_document_to_folder requires non-empty folder_id and document_id.
• Required string inputs are trimmed before the request is sent. Blank or whitespace-only required values return a JSON error response instead of attempting the write.
• Optional parent_id and group_id values are trimmed when provided and then forwarded upstream without additional local business rules.
• Rename and delete operations surface upstream missing-folder, access, or context errors as JSON error responses instead of false success payloads.

mendeley_get_file_content accepts either a library document ID or a catalog_id. Catalog entries often do not have downloadable files, so a no-file result is expected in many cases.

Configuration

Environment Variables

If you prefer not to use mendeley-auth login, you can configure credentials via environment variables:

# 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"

Optional tuning variables:

# 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"

Or in your MCP config:

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

Auth Commands

# Check authentication status
mendeley-auth status

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

# Remove saved credentials
mendeley-auth logout

Refreshed credential storage

When a saved login's access token expires, the server refreshes it and writes the new tokens back to the same place the login was stored: the system keyring, or the credentials file, which is replaced atomically with private permissions. The next server start therefore begins with a valid token instead of a refresh round trip.

Credentials supplied through environment variables are never written anywhere; those deployments manage token durability themselves. If saving fails, the running session keeps its refreshed tokens and logs a warning without credential details, and the next start may need mendeley-auth login again.

Development

Setup

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

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=mendeley_mcp

# Type checking
mypy src/mendeley_mcp

# Linting
ruff check src/

Testing with MCP Inspector

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

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

Architecture

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

Important: This server runs locally on your machine. Your credentials and data never pass through any third-party servers - all communication is directly between your computer and Mendeley's API.

Credential Storage: When keyring support is available, OAuth tokens and the client secret are stored in your system's native keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service), and only the client ID is saved in ~/.config/mendeley-mcp/credentials.json. Without keyring support, credentials are saved in that file with private permissions. Signed download URL queries are redacted from HTTPX request logs and omitted from download error messages.

Rate Limits

Mendeley API rate limits are per-user. If you hit rate limits:

• The server implements automatic token refresh
• Wait a few minutes and retry
• For heavy usage, consider spreading requests over time

Troubleshooting

"No credentials found"

Run mendeley-auth login to authenticate.

"Token expired"

Your access token has expired. The server refreshes it automatically using your refresh token and saves the new token to your keyring or credentials file. If this fails, run mendeley-auth login again.

"401 Unauthorized"

Your app may have been deauthorized. Re-authenticate with mendeley-auth login.

Server not appearing in Claude

1. Check the config file path is correct for your OS
2. Ensure JSON is valid (no trailing commas)
3. Restart Claude Desktop completely
4. Check Claude's logs for errors

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

License

MIT License - see LICENSE file.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Mendeley or Elsevier. Mendeley is a trademark of Elsevier B.V.

Acknowledgments

• Model Context Protocol by Anthropic
• MCP Python SDK
• Mendeley API documentation

Contributors

• @roych98 — reported the MCP SDK 2.x install break, supplied the interim pin, and wrote the SDK v2 migration (#8)
• @im-alexandre — folder management tools, adapted from #2
• @Storkholm — reported and isolated the structured-content client behavior (#11)
• @HasiVS — requested tags and keywords on document update (#12) and reported folder-list truncation (#13)