mendeley-mcp 0.1.3

MCP server for Mendeley reference manager - search, retrieve, and manage your academic library

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
• Browse folders - Navigate your collection structure
• 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
• Add documents - Create new entries in your library

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

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

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.]"

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"

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

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: Your OAuth tokens and client secret are stored securely in your system's native keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service). Only the non-sensitive client ID is stored in ~/.config/mendeley-mcp/credentials.json.

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 will attempt to refresh it automatically using your refresh token. 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
• FastMCP Python framework
• Mendeley API documentation