# Mendeley MCP Server for Antigravity & AI Assistants

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()

Connect your **Mendeley** reference library to **Google Antigravity (AGY)**, **Claude Desktop**, **Cursor**, and other Model Context Protocol (MCP) clients. Search your academic library, retrieve full-text PDF papers, access annotations, generate BibTeX citations, and query Mendeley's global catalog of 100M+ research publications using natural language prompts.

---

## 🏛 Architecture

```mermaid
flowchart LR
    A["Elsevier / Mendeley API<br/>(OAuth 2.0 & REST)"] <--> B["mendeley-mcp Server<br/>(Python Stdio)"]
    B <--> C["MCP Protocol<br/>(JSON-RPC 2.0)"]
    C <--> D["AI Assistant Client<br/>• Google Antigravity (AGY)<br/>• Claude Desktop<br/>• Cursor"]
```

---

## 🌟 Key Features

- **Personal Library Search**: Search papers by title, author, abstract, or keywords.
- **Full-Text PDF Extraction**: Retrieve and read raw text from attached research papers directly into agent context.
- **Annotations & Highlights**: Surface notes and highlights previously made on PDFs in Mendeley.
- **Global Catalog Search**: Access Mendeley's 100M+ academic paper database.
- **DOI Lookup**: Fetch metadata and papers instantly from any DOI.
- **Folder & Collection Management**: Browse nested collections, create, rename, and organize references.
- **BibTeX Generation**: Export formatted BibTeX citation entries for individual papers or whole folders.
- **Secure Token Management**: OAuth 2.0 authentication with automatic refresh token persistence via system keyring.

---

## 📋 Prerequisites

1. **Python 3.10+** (Tested on Python 3.12).
2. **Mendeley Account**: Register at [mendeley.com](https://www.mendeley.com/).
3. **Mendeley Developer Application**:
   - Visit [dev.mendeley.com/myapps.html](https://dev.mendeley.com/myapps.html) and sign in.
   - Click **Register a new app**.
   - App Name: `Antigravity MCP` (or similar).
   - Redirect URL: `http://localhost:8080` (or `http://localhost:8585/callback`).
   - Flow: Select **Authorization code** flow (not Legacy).
   - Save your **Client ID** and **Client Secret**.

---

## 🚀 Quick Start

### 1. Installation

Install via `pip` or `uv`:

```bash
pip install -r requirements.txt
# or directly
pip install mendeley-mcp
```

### 2. Authentication (OAuth 2.0)

If your app was registered with the standard URI `http://localhost:8585/callback`, run:

```bash
mendeley-auth login
```

If your app was registered with **`http://localhost:8080`** (or a custom port), use the included `mendeley_oauth.py` script:

```bash
python mendeley_oauth.py --client-id <YOUR_CLIENT_ID> --client-secret <YOUR_CLIENT_SECRET> --port 8080
```

> [!NOTE]
> You can also copy `.env.example` to `.env` and set your credentials:
> ```bash
> cp .env.example .env
> python mendeley_oauth.py
> ```

This opens your browser to sign in to Elsevier/Mendeley. Once authorized, tokens are stored securely in your system keyring and `~/.config/mendeley-mcp/credentials.json`.

Verify status anytime:
```bash
python -m mendeley_mcp.auth status
```

---

## ⚙️ MCP Client Configuration

### 1. Google Antigravity (AGY)

Add the `mendeley` server to your Antigravity configuration files:

- **Global Config**: `~/.gemini/config/mcp_config.json`
- **IDE Config**: `~/.gemini/antigravity-ide/mcp_config.json`

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

*On Windows, you can also specify the absolute executable path if needed:*
```json
{
  "mcpServers": {
    "mendeley": {
      "command": "C:\\Users\\<YourUser>\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\mendeley-mcp.exe"
    }
  }
}
```

Enable the server in `~/.gemini/mcp-server-enablement.json`:
```json
{
  "mendeley": {
    "enabled": true
  }
}
```

### 2. Claude Desktop

Add to your `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

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

---

## 🛠 Available Tools (18 Tools)

| Tool | Scope | Description |
| :--- | :--- | :--- |
| `mendeley_search_library` | Library | Search papers in your personal library by title, author, or keyword |
| `mendeley_get_document` | Library | Get comprehensive metadata, DOI, tags, and abstract for a known document ID |
| `mendeley_list_documents` | Library | Browse documents with optional folder filtering and sorting |
| `mendeley_list_folders` | Folders | View collections and folder hierarchy |
| `mendeley_create_folder` | Folders | Create a new collection or subfolder |
| `mendeley_rename_folder` | Folders | Rename an existing folder |
| `mendeley_delete_folder` | Folders | Delete a collection folder |
| `mendeley_add_document_to_folder` | Organization | Move/add an existing document to a folder |
| `mendeley_remove_document_from_folder` | Organization | Remove document from folder without deleting it |
| `mendeley_search_catalog` | Global | Search Mendeley’s global database of 100M+ research publications |
| `mendeley_get_by_doi` | Global | Fetch publication details and citation by DOI |
| `mendeley_add_document` | Management | Create and add a new reference to your library |
| `mendeley_update_document` | Management | Update bibliographic fields of an existing reference |
| `mendeley_delete_document` | Management | Permanently delete a document from your library |
| `mendeley_get_annotations` | PDF | Extract reader annotations, highlights, and notes |
| `mendeley_export_bibtex` | Citation | Generate formatted BibTeX citation entries |
| `mendeley_get_file_content` | Files | Download attached document files/PDFs |
| `mendeley_get_document_text` | Text | Extract raw text from attached PDFs for agent reading |

---

## 🔍 Verification & Testing

Verify that Mendeley MCP can initialize and communicate over stdio:

```powershell
python -c "
import subprocess, json

proc = subprocess.Popen(['mendeley-mcp'], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
proc.stdin.write(json.dumps({'jsonrpc': '2.0', 'id': 1, 'method': 'initialize', 'params': {'protocolVersion': '2024-11-05', 'capabilities': {}, 'clientInfo': {'name': 'test', 'version': '1.0'}}}) + '\n')
proc.stdin.flush()
print('Handshake Response:', proc.stdout.readline())
proc.terminate()
"
```

---

## 🔒 Security Best Practices

> [!CAUTION]
> **Never commit credentials to version control!**
> - Ensure `.env`, `credentials.json`, and any files containing your Client ID or Secret are included in `.gitignore`.
> - Mendeley API keys should always remain local to your machine.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).