# zotero-pdf-mcp

An MCP server that gives Claude access to a Zotero library over the **web API**,
including the ability to *look at* the PDFs — rendered pages, not just extracted
text, so figures, gels, micrographs and layout are visible.

Existing Zotero MCP servers return extracted text only. This one renders pages
to PNG and returns them as image content, which is the difference between an
assistant that can read a paper's prose and one that can read its figures.

## Design constraints

- **Web API only.** Talks to `api.zotero.org` and never to the local Zotero
  client on `localhost:23119`. If your Zotero is set to download attachments on
  demand, going through the local client would make it fetch and retain files
  you have deliberately offloaded to Zotero storage. This server cannot cause
  that.
- **Nothing written to disk.** PDF bytes are held in memory, capped at four
  documents, and discarded when the process exits.
- **Read-only.** Every request is a GET; there are no write operations of any
  kind. A read-only API key is sufficient.
- **The credential never leaves Zotero.** File downloads redirect to a storage
  host; the server re-issues that request without the Zotero headers so your API
  key is not forwarded to a third party.

Attachments stored in Zotero File Storage can be fetched. Linked files cannot —
their bytes only ever existed on the machine that added them. `zotero_item_info`
reports which is which.

## Tools

| Tool | Purpose |
| --- | --- |
| `zotero_search` | Search the library; returns item keys, authors, years, titles. |
| `zotero_item_info` | Full metadata for one item, plus its attachments and whether each is fetchable. |
| `zotero_pdf_text` | Extract text from an item's PDF. Cheap; use this first. |
| `zotero_pdf_pages` | Render pages as images. Max 8 per call. This is the one that shows figures. |

## Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` inside
the existing `mcpServers` object:

```json
"zotero-pdf": {
  "command": "/opt/homebrew/bin/uvx",
  "args": ["--from", "git+https://github.com/USER/zotero-pdf-mcp", "zotero-pdf-mcp"],
  "env": {
    "ZOTERO_API_KEY": "your_read_only_key",
    "ZOTERO_LIBRARY_ID": "your_numeric_userid",
    "ZOTERO_LIBRARY_TYPE": "user"
  }
}
```

Use the absolute path to `uvx` (`which uvx`) rather than the bare command —
GUI-launched processes often do not inherit your shell's PATH, and that is the
most common reason an MCP server silently fails to start.

For a private repo, use `git+ssh://git@github.com/USER/zotero-pdf-mcp` so the
fetch authenticates with your SSH key.

### Environment

| Variable | Meaning |
| --- | --- |
| `ZOTERO_API_KEY` | Read-only key from <https://www.zotero.org/settings/keys/new> |
| `ZOTERO_LIBRARY_ID` | Your **numeric** userID, printed at the top of the keys page. Not your username. |
| `ZOTERO_LIBRARY_TYPE` | `user` (default) or `group` |

Never commit the key. It belongs in the config's `env` block and nowhere else.

## Usage

Ask for text before pictures — rendering pages is far more expensive than
extracting text:

> Find the Vujanovic 2017 paper in my library, pull the text, then show me the
> figures from pages 4 and 5.

## Licence

MIT.