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.

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.