# Zotero MCP

Read-only MCP server for your local [Zotero](https://www.zotero.org) library. Browses collections, inspects paper metadata, and extracts full text from PDFs -- all via FastMCP tools.

## Requirements

- Zotero desktop synced to `~/Zotero/zotero.sqlite` (default on Linux)
- Python 3.13+
- [uv](https://docs.astral.sh/uv/)

## Configuration

This is an MCP server. You register it in your coding agent's MCP configuration, then the agent can use its tools.

Most agents accept a similar configuration. For example, in Opencode you add it to the `opencode.json`:

```json
{
  "mcp": {
    "zotero-mcp": {
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/404Simon/zotero-mcp",
        "zotero-mcp"
      ],
      "enabled": true,
      "type": "local"
    }
  }
}
```

After this setup, the agent discovers the tools automatically and you can simply ask it things like:

> "What papers on RAG are in my library, and what's the abstract of the most recent one?"

## Tools

### `list_library`

List all collections and papers as a formatted tree. Optionally filter by collection name, paper title, or author.

| Argument | Type                | Description                                                          |
| -------- | ------------------- | -------------------------------------------------------------------- |
| `query`  | `string` (optional) | Filter by collection name, paper title, or author (case-insensitive) |

Each paper line includes its item key in `[KEY]` brackets. Use that key with `paper_details` or `paper_text`. Filtered output only shows the matching subtree, with matching collections and their ancestors.

```text
├── AI (2 papers)
│     [N3G6XKB9] [preprint] Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (2021) - Patrick Lewis
│     [PPJJCMXJ] [book] Grundkurs Künstliche Intelligenz: eine praxisorientierte Einführung (2021) - Wolfgang Ertel
├── Bachelorarbeit (42 papers)
│   ├── GraalVM (4 papers)
│   │     [DSUERN67] [book] Supercharge your applications with GraalVM ... (2021) - A. B. Vijay Kumar
│   └── Java Performance (1 papers)
│         [Q3ANMGC3] [conferencePaper] Applying Optimizations for Dynamically-typed Languages to Java (2017) - Matthias Grimmer
│   [MTSF327R] [book] Pro Spring Boot 3: An Authoritative Guide with Best Practices (2024) - Felipe Gutierrez
├── Studienarbeit (49 papers)
│     [T3ZCDWC7] [preprint] MMLU-Pro: A More Robust and Challenging Multi-Task Language Understanding Benchmark (2024) - Yubo Wang
├── T3000 (4 papers)
│     [DTZF77Y4] [webpage] Conventional Commits (n.d.) - Unknown
├── TheGreenEpoch (8 papers)
│     [YINRQ63P] [preprint] Distributed LLM Pretraining During Renewable Curtailment Windows (2026) - Philipp Wiesner
└── VesSkel (19 papers)
      [ZUXQUGHW] [journalArticle] Open-source analysis and visualization of segmented vasculature datasets with VesselVio (2022) - Jacob R. Bumgarner
```

### `paper_details`

Get full metadata for a paper by its item key. Obtain the key from `list_library` output (shown as `[KEY]`) or from `search_papers` results.

| Argument   | Type                | Description                                                                           |
| ---------- | ------------------- | ------------------------------------------------------------------------------------- |
| `item_key` | `string` (required) | Zotero item key (shown as `[KEY]` in list_library output or in search_papers results) |

Returns title, type, key, added/modified dates, authors, all field metadata, collection memberships, and PDF attachment info:

```text
Title: MMLU-Pro: A More Robust and Challenging Multi-Task Language Understanding Benchmark
Type: preprint
Key: T3ZCDWC7
Authors: Yubo Wang, Xueguang Ma, Ge Zhang, Yuansheng Ni, ...
date: 2024-11-06
DOI: 10.48550/arXiv.2406.01574
url: http://arxiv.org/abs/2406.01574
abstractNote: In the age of large-scale language models, benchmarks like the Massive Multitask Language Understanding (MMLU) ...
Collections: Studienarbeit
PDF: Wang et al. - 2024 - MMLU-Pro A More Robust and Challenging Multi-Task Language Understanding Benchmark.pdf
```

### `search_papers`

Search all papers by title or author. Returns structured results with item keys.

| Argument | Type                | Description                                              |
| -------- | ------------------- | -------------------------------------------------------- |
| `query`  | `string` (required) | Search term (case-insensitive, matches title and author) |

```json
[{"key": "ZUXQUGHW",
  "title": "Open-source analysis and visualization of segmented vasculature datasets with VesselVio",
  "type": "journalArticle", "year": "2022",
  "first_author": "Jacob R. Bumgarner",
  "authors": ["Jacob R. Bumgarner", "Randy J. Nelson"],
  "url": "https://linkinghub.elsevier.com/retrieve/pii/S2667237522000443"},
 {"key": "6DU4XPQQ",
  "title": "Robust Vessel Segmentation in Fundus Images",
  "type": "journalArticle", "year": "2013",
  "first_author": "A. Budai",
  "authors": ["A. Budai", "R. Bock", "A. Maier", "J. Hornegger", "G. Michelson"],
  "url": "http://www.hindawi.com/journals/ijbi/2013/154860/"}]
```

### `paper_text`

Extract the full text of a paper's PDF using [PyMuPDF](https://pypi.org/project/PyMuPDF/) (bundled as a Python dependency, no system tools needed). Requires a PDF attachment stored in `~/Zotero/storage/`.

| Argument   | Type                | Description                                                                           |
| ---------- | ------------------- | ------------------------------------------------------------------------------------- |
| `item_key` | `string` (required) | Zotero item key (shown as `[KEY]` in list_library output or in search_papers results) |

Returns the raw extracted text, starting with the title, authors, and abstract:

```text
            MMLU-Pro: A More Robust and Challenging
              Multi-Task Language Understanding Benchmark
                           1Yubo Wang∗, 1Xueguang Ma∗, 1Ge Zhang, 1Yuansheng Ni, 1Abhranil Chandra, ...
                                 1University of Waterloo, 2University of Toronto, 3Carnegie Mellon University
                                            Abstract
                                In the age of large-scale language models, benchmarks like the Massive Multitask
                                Language Understanding (MMLU) have been pivotal in pushing the boundaries
                                of what AI can achieve in language comprehension and reasoning across diverse
                             domains. ...
```

## File structure

```text
src/
  main.py    # FastMCP server, tool definitions
  zotero.py  # SQLite queries, data models, formatting
```

The database is read directly from `~/Zotero/zotero.sqlite`. PDFs are resolved from `~/Zotero/storage/`. No API key needed.