# zotero-mcp

MCP server for natural-language search over a local Zotero library (metadata,
abstracts, notes, and PDF full text) via Claude.

## Setup on a new machine

Requires Zotero installed and synced locally (library sync + file sync for
PDFs), and Python 3.

```bash
git clone <this-repo-url>
cd zotero-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

python extract.py       # pulls papers.json from ~/Zotero/zotero.sqlite
python build_index.py   # embeds papers.json -> data/embeddings.npy

claude mcp add -s user zotero-search -- "$(pwd)/venv/bin/python" "$(pwd)/server.py"
```

Start a new Claude Code session and the tools `search_zotero_library`,
`get_zotero_paper`, `get_zotero_paper_fulltext`, and `refresh_zotero_index`
will be available in every project on that machine.

## Files

- `extract.py` — reads `~/Zotero/zotero.sqlite` (via a copy, since Zotero
  locks the file while running) and writes `data/papers.json`: title,
  creators, year, venue, DOI, tags, collections, abstract, notes, and
  resolved PDF path for every paper-type item.
- `build_index.py` — embeds each paper (title + authors + venue + tags +
  abstract + notes) locally with `BAAI/bge-small-en-v1.5` (fastembed, CPU,
  no API calls) into `data/embeddings.npy`.
- `server.py` — the MCP server exposing the four tools above.

`data/` is gitignored — it's derived from your local Zotero library and
should be rebuilt on each machine (`extract.py` + `build_index.py`), not
copied between machines.