zotero-local-mcp

Two MCP servers for a local Zotero 10 library, plus a weekly alert script:

• zotero-local-mcp (librarian): search and edit the library, faceted tagging with a controlled vocabulary, citekeys, imports by DOI/PMID/ISBN, metadata audit and repair, duplicates, retraction check, open-access PDFs, notes, collections, undo.
• zotero-scholar-mcp (researcher): PubMed and OpenAlex search with "already in library" flags, citation graph, manuscript citation check, CSL JSON bibliographies for Quarto, import queue. It cannot write to Zotero.
• zotero-alerts: runs saved searches from an Obsidian note and writes new works to an Inbox note. No AI model.
• zotero-review: preview or apply several tag review notes from the terminal (zotero-review apply 13-31: note numbers, or paths in the vault). Asks before it writes; notes already applied are left out.
• zotero-bakeoff: model test for tagging. sample fixes 25 items and writes a reference note for your own tags; run --model X runs each model through opencode run (tools bakeoff_items, bakeoff_submit, no library writes); score writes precision, recall, edits needed, tokens and cost per model.

The library is reached only through Zotero's local API on 127.0.0.1:23119: no zotero.org key, changes appear in Zotero at once and sync as normal edits (WebDAV file sync is not affected). Outside metadata comes from Crossref, PubMed (NCBI E-utilities), OpenAlex, Unpaywall and Open Library.

Safety

• Every write tool defaults to dry_run=true and returns a preview.
• Added tags must be in the vocabulary file. Tags that start with _ are system tags. Imports never add keywords or MeSH headings as tags.
• Each item write sends the item version; concurrent edits in Zotero are kept.
• Every applied write goes to a journal (~/.local/share/zotero-local-mcp/journal/). undo reverts it, skipping items edited since. Imports and attached PDFs are undone by moving them to the trash.
• No DELETE requests. Items go to the trash.
• The researcher's library client refuses every write except creating a new child note (attach_note: a short summary plus an obsidian:// link, journaled, undone by the librarian). Works it proposes go to an import queue note that a person ticks; the librarian imports the ticked lines. Queue labels are sanitised so they cannot create or tick lines.
• Duplicate detection by title needs the same year and first author, and no conflicting DOI/PMID. find_duplicates also finds titles cut off during import, shows the evidence for each item, and says when the item types differ (Zotero's Duplicate Items view shows only items of the same type).
• Tag limits per facet come from the vocabulary (max_per_facet: topic=4, type=2); tag_items skips a change that would go over. replace makes the given tags the complete set for those facets. write_tag_review writes a review note (a table of proposed tags, checked against the vocabulary, never overwriting a note); apply_tag_review applies the edited note exactly, removes the review marker, lists items whose tags changed after the note was written, and refuses a note that was already applied unless again=true.

Tools

Requirements

• Zotero 10 or later, running, with Settings > Advanced > "Allow other applications on this computer to communicate with Zotero".
• uv (brew install uv).

Install

1. Quit Zotero. Copy ~/Zotero to a backup location. Start Zotero.
2. Copy examples/zotero.env to ~/.config/opencode/zotero.env. Fill in ZOTERO_CONTACT_EMAIL (required for Unpaywall).
3. Run uv sync && uv run pytest -q. All tests must pass.
4. Run ZOTERO_MCP_ENV=~/.config/opencode/zotero.env uv run zotero-local-mcp --check. The result must show "zotero": "reachable".
5. Add the servers and the two agents to OpenCode: see examples/opencode-global.jsonc.
6. Optional: weekly alerts with launchd, see examples/launchd/.

Configuration

Settings come from environment variables or from the file named by ZOTERO_MCP_ENV (default ~/.config/zotero-local-mcp/env), one KEY=VALUE per line.

Vocabulary file

---
required_facets: topic, status
single_facets: status
---
## topic
- `topic/spirometry` Spirometry. aliases: Spirometry, FEV1

Alerts file

---
days: 7
max_per_query: 20
---
## pubmed
- `FeNO[tiab] AND asthma[tiab]` FeNO in asthma
## openalex
- `health data literacy` Health data literacy

Write authorization

The first write opens a Zotero dialog. Choose "Always Allow"; the key is saved in the state folder (permissions 600). With "Allow", each batch shows the dialog again. To revoke: Zotero > Settings > Advanced > Clear Write Authorizations.

Citekeys

jacinto2026, jacinto2026a. Stored in the native citationKey field when the item has one, otherwise as Citation Key: in Extra. Better BibTeX reads both.

Not yet checked against a real Zotero 10

The tests use simulated services. Check on first use: trash and undo, the citekey location, one import, one PDF attachment (local file upload).

Development

uv sync
uv run pytest -q

tests/fake_zotero.py imitates the Zotero 10 local API; tests/fake_external.py gives canned Crossref, PubMed, OpenAlex, Unpaywall and Open Library responses.