Zotero MCP Server: Zotero hoeft niet open, 10,000-PDF-zoekopdracht in ~20 ms

Q: Ondersteunt de Zotero MCP-server zowel Python als JavaScript?

Ja. Er zijn twee gelijkwaardige shells: @docsagent/mcp-zotero op npm voor JavaScript/Node-gebruikers en docsagent-mcp-zotero op PyPI voor Python 3.10+. Beide bieden dezelfde 8 tools met dezelfde schema's, foutcodes en schrijfpoort, en beide beheren dezelfde meegeleverde C++-kern.

Als u een Zotero MCP-server van de eerste generatie hebt geprobeerd, herinnert u zich het ritueel: Zotero moest open staan, de lokale API moest zijn ingeschakeld, en elke zoekopdracht kroop metadatarecord voor metadatarecord door uw bibliotheek. Voor een demo is dat prima. Het is niet prima wanneer uw bibliotheek 5,000 PDF's bevat en een agent twintig zoekopdrachten afvuurt voordat u een zin hebt uitgetypt.

De nieuwe Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, uitgebracht op 21 september 2026 — is een andere machine. Hij levert twee shells (JavaScript en Python) bovenop een permanent draaiende native C++-zoekkern die uw Zotero-gegevensmap rechtstreeks leest. Zoeken werkt zonder Zotero te openen, en bibliotheken met 10,000+ PDF's worden een kennisbank op millisecondenniveau voor Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline of elke andere MCP-client.

Dit is de gids voor de nieuwe versie: wat er is veranderd, hoe u hem in beide runtimes installeert, de 8 tools die uw agent krijgt, en de benchmarkcijfers voor echt grote bibliotheken.

Wat is er nieuw in Zotero MCP Server 4.0

Twee shells, één kern. Hetzelfde toolcontract is beschikbaar als TypeScript-pakket op npm (@docsagent/mcp-zotero) en als Python-pakket op PyPI (docsagent-mcp-zotero). Kies de runtime die uw stack al gebruikt — de tools, schema's, foutcodes en de schrijfpoort zijn identiek.
Zotero hoeft niet te worden gestart. De C++-kern leest ~/Zotero/zotero.sqlite plus de map storage/ rechtstreeks, zodat indexeren en zoeken blijven werken terwijl Zotero gesloten is — of nooit op die machine is geïnstalleerd.
Een permanente service, geen subproces per aanroep. De kern draait op de achtergrond op http://127.0.0.1:23120/rpc, bouwt zijn index opnieuw op wanneer uw bibliotheek verandert, en blijft warm bij herstarts van de MCP-client. Uw agent betaalt nooit een koudestarttoeslag.
Gebouwd voor grote bibliotheken. Geïnverteerde index met BM25-volledige-tekstzoekopdracht + passageranking over 1,000+ PDF's bij ~15 ms, met een geheugengebruik in de lage honderden MB's in plaats van gigabytes.
8 MCP-tools (5 lezen + 3 schrijven) met door JSON-schema gevalideerde argumenten, tokenbudgetten, ontdubbeling van resultaten en een drielaagse veiligheidspoort voor schrijfacties.
Twee transporten. stdio voor lokale MCP-clients; Streamable HTTP (/mcp) met origin-controles, API-key- of OAuth 2.0-authenticatie (RFC 7662) en RBAC per verzoek wanneer u hem op afstand uitrolt.
Eén configuratiebestand. ~/.docsagent/config.json wordt gedeeld door de JS-shell, de Python-shell en de C++-kern.

Hoe het werkt: twee shells bovenop één native kern

MCP Client (Claude Code / Claude Desktop / Cursor / Codex / Gemini CLI / Qwen Code / Cline)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← @docsagent/mcp-zotero  (TypeScript)  or  docsagent-mcp-zotero  (Python)
   · spec-driven tool schemas, argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
        │  JSON-RPC 2.0 over HTTP  ({coreHost}:{httpPort}/rpc)
        ▼
DocsAgent Core  (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/ directly
   · builds & serves the full-text index (BM25 + passage ranking)

De splitsing is belangrijk. De shell is dun — hij bevat de toolschema's, valideert argumenten, handhaaft tokenbudgetten en raakt uw Zotero-bestanden nooit aan. De kern doet het zware werk in C++, en daarom bedient dezelfde engine zowel het npm- als het PyPI-pakket met byte-identiek gedrag.

Snelstart: verbind Zotero in 3 stappen met uw AI-agent

Optie A — JavaScript / npm

# 1. start the resident search core (background service)
npx @docsagent/mcp-zotero start
npx @docsagent/mcp-zotero status    # pid / endpoint / version

Voeg daarna de server toe aan de instellingen van uw MCP-client (Claude Desktop, Cursor, Cline, Qwen Code, …):

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "npx",
      "args": ["-y", "@docsagent/mcp-zotero"]
    }
  }
}

Optie B — Python

# 1. install the Python shell (ships the same bundled core binaries)
pip install docsagent-mcp-zotero
docsagent-mcp-zotero core start
docsagent-mcp-zotero core status

Registreer de Python-shell daarna op dezelfde manier:

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "docsagent-mcp-zotero",
      "args": []
    }
  }
}

Herstart uw MCP-client en vraag iets als "Wat zegt mijn Zotero-bibliotheek over batterijdegradatie in natrium-ioncellen?" — de agent roept search aan, krijgt BM25-gerangschikte passages met zotero:KEY-citaties, en antwoordt vanuit uw PDF's in plaats van vanaf het open web.

Beide CLI's bieden ook commando's voor de levenscyclus van de kern — start, stop, restart, status (Python voert ze uit onder een core-subcommando, dus docsagent-mcp-zotero core restart) — plus --transport streamable-http wanneer u /mcp via het netwerk wilt aanbieden.

De 8 tools die uw agent kan aanroepen

Tool	Type	Wat het doet
`list_sources`	Lezen	Elke doorzoekbare bron met mogelijkheden en documentaantallen. Roep dit eerst aan.
`search`	Lezen	Zoeken over bibliotheken heen in items, annotaties of notities; diepte `ids` / `snippets` / `full`, filters voor tags, jaarbereik, itemtype, auteurs, collecties.
`get_content`	Lezen	Lees één entry als op de query gerangschikte passages (`k`) of volledige tekst met offset-paginering.
`get_metadata`	Lezen	Metadata, abstract, annotaties, notities en citaties (BibTeX / CSL-JSON / opgemaakt).
`list_library`	Lezen	Blader door collecties, items, tags, opgeslagen zoekopdrachten en losse notities.
`import_item`	Schrijven	Importeer lokale PDF's of los DOI / ISBN / arXiv-ID's op, met optionele automatische collectieclassificatie.
`add_note`	Schrijven	Schrijf een Markdown-notitie terug naar een item als Zotero-kindnotitie, met rollback.
`batch_modify`	Schrijven	Voeg collecties of tags in bulk toe aan of verwijder ze bij maximaal 200 items.

Schrijftools worden helemaal niet geregistreerd tenzij u enableWrites: true instelt. Zelfs dan geeft een niet-bevestigde aanroep een voorbeeld terug en verbruikt die geen quotum, zijn bevestigde schrijfacties snelheidsbeperkt (standaard 30/hour), en elke batch_modify van meer dan 20 items komt terug met requiresConfirmation. Een agent kan uw bibliotheek de hele dag lezen; hij kan haar niet stilletjes herschrijven.

Prestaties: 10,000 PDF's, 42 GB, geïndexeerd in ~7 minuten

De kern in deze MCP-server is dezelfde indexerings- en retrieval-engine als achter PapersGPT's zoekbenchmark. Cijfers uit een echte Zotero-installatie:

Bibliotheekgrootte	Ruwe data	Indexopbouw	Gem. zoektijd	Geheugen (RSS)	Indexgrootte
1,000 PDF's	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000 PDF's	42 GB	421 s (7 m 01 s)	19.5 ms	2.21 GB	901 MB

Op een bewust bescheiden opstelling — 4 cores / 8 GB RAM — duurde het indexeren van 1,506 PDF's (4.5 GB) 141 seconden, terwijl het proces 227 MB geheugen vasthield, met een gemiddelde retrieval van ~15 ms. Het patroon dat ertoe doet:

Indexeren schaalt ongeveer lineair. Tien keer zoveel PDF's, tien keer zoveel opbouwtijd — en u betaalt die één keer per nieuw document, niet per vraag.
Retrieval blijft vlak. 13 ms bij 1,000 papers, 19.5 ms bij 10,000. Meer papers toevoegen maakt uw agent niet trager.
Geheugen blijft bescheiden. Automatisch offloaden houdt een bibliotheek van 42 GB doorzoekbaar binnen ongeveer 2 GB RAM.
Alles is offline. Geen cloudaanroepen voor indexeren of retrieval, dus het werkt in een vliegtuig, in een afgesloten labnetwerk of onder een embargo.

Waarom "Zotero hoeft niet te worden gestart" de workflow verandert

Klassieke Zotero MCP-servers zijn dunne wrappers rond de Zotero local API (http://localhost:23119/api): geen Zotero-proces, geen antwoorden. Die ene afhankelijkheid bepaalt alles — u kunt uw bibliotheek niet doorzoeken vanuit een container, een remote dev-box, een headless script of een SSH-sessie; u kunt niet zoeken terwijl Zotero midden in een sync zit; en elke aanroep is een request-roundtrip in plaats van een index-lookup.

Omdat de DocsAgent-kern de database rechtstreeks leest, is de lezende helft van de workflow losgekoppeld van de Zotero-app:

	Op API gebaseerde Zotero MCP-servers	Zotero MCP Server 4.0
Zotero moet draaien om te zoeken	Ja	Nee
Zoekbackend	Zotero local API-aanroepen	Native C++ BM25 + passage-index
Zoeklatentie bij 10,000 PDF's	Honderden ms tot seconden	~20 ms
Runtimes	Meestal één	JavaScript + Python
Remote / HTTP-transport	Zeldzaam	Streamable HTTP met auth + RBAC
Schrijfveiligheid	Meestal handmatig	Drielaagse poort + snelheidslimiet

Eén eerlijke kanttekening: schrijfacties gaan nog steeds via Zotero's eigen local API, zodat Zotero de bron van waarheid voor uw bibliotheek blijft. Als u wilt dat de agent PDF's importeert, notities toevoegt of items opnieuw tagt, moet Zotero voor die specifieke stap draaien. Bij indexeren, zoeken en lezen is dat nooit nodig.

Gebruiksscenario's: wat onderzoekers er echt mee doen

Onderzoek in de editor met Claude Code of Cursor. Schrijf uw paper en laat de agent passages, abstracts en BibTeX rechtstreeks uit uw eigen bibliotheek halen terwijl u typt — geen kopiëren en plakken, geen browsertabbladen.
Literatuur triage in de terminal met Codex of Gemini CLI. "Zoek elke paper in mijn bibliotheek die een efficiëntie van energieomzetting boven 20% rapporteert en voeg ze toe aan de Perovskite-collectie" — search gevolgd door batch_modify.
Offline lezen. In een vliegtuig of in het veld beantwoordt de index vragen lokaal; niets heeft een netwerk nodig.
Groepsbibliotheken. Richt zoteroGroups op de gedeelde bibliotheken van uw lab en doorzoek ze naast uw persoonlijke collectie.
Agent-skills. Het project publiceert ook een draagbare SKILL.md, zodat agenten die skills ondersteunen de workflow "eerst zoeken, dan citeren" kunnen leren in plaats van te gokken naar toolargumenten.

Privacy en veiligheid

Uw PDF's verlaten nooit uw machine: indexeren en retrieval zijn 100% lokaal, en er worden geen documenten naar een clouddienst gestuurd. Wanneer u schrijfacties bewust inschakelt, zijn ze afgeschermd met een poort, vooraf te bekijken, snelheidsbeperkt en omkeerbaar. Wanneer u de server bewust via HTTP blootstelt, krijgt u origin-controles, token-authenticatie en RBAC per verzoek in plaats van een open poort.

Veelgestelde vragen

Moet ik Zotero laten draaien zodat de MCP-server werkt?

Nee — voor zoeken en lezen. De kern leest uw Zotero-gegevensmap (zotero.sqlite en storage/) rechtstreeks, dus indexeren en zoeken werken met Zotero gesloten, en zelfs op een machine waarop de Zotero-desktopapp niet draait. Alleen de drie schrijftools (items importeren, notities toevoegen, bulkbewerkingen van tags/collecties) gaan via Zotero's local API, dus daarvoor moet Zotero open zijn.

Ondersteunt de Zotero MCP-server zowel Python als JavaScript?

Ja. Er zijn twee gelijkwaardige shells: @docsagent/mcp-zotero op npm voor JavaScript/Node-gebruikers en docsagent-mcp-zotero op PyPI voor Python 3.10+. Beide bieden dezelfde 8 tools met dezelfde schema's, foutcodes en schrijfpoort, en beide beheren dezelfde meegeleverde C++-kern.

Hoe grote Zotero-bibliotheek kan hij aan?

Bibliotheken met duizenden PDF's zijn routine: 1,000 PDF's (4.2 GB) worden in ongeveer 52 seconden geïndexeerd en in ~13 ms doorzocht; 10,000 PDF's (42 GB) worden in ongeveer 7 minuten geïndexeerd en in ~19.5 ms doorzocht. De opbouwtijd van de index groeit ongeveer lineair met de bibliotheekgrootte, terwijl de zoeklatentie vrijwel constant blijft.

Wordt mijn Zotero-bibliotheek ergens naartoe geüpload?

Nee. De kern bouwt en bedient zijn index volledig op uw machine, en zoeken vereist geen netwerktoegang. Niets van uw papers wordt naar PapersGPT of een derde partij gestuurd.

Kan de AI-agent mijn Zotero-bibliotheek aanpassen?

Alleen als u het toestaat. Schrijftools worden niet geregistreerd tenzij enableWrites op true staat; niet-bevestigde aanroepen geven een voorbeeld terug; bevestigde schrijfacties zijn snelheidsbeperkt (standaard 30/hour); en batches van meer dan 20 items vereisen expliciete bevestiging.

Welke AI-clients worden ondersteund?

Elke MCP-client. Het project documenteert Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI en Qwen Code, en levert een Streamable HTTP-transport voor clients die op afstand verbinden in plaats van via stdio.

Hoe verschilt dit van de oudere PapersGPT MCP-opzet?

De oudere opzet was een brug met één doel, gebouwd rond de Zotero local API. Versie 4.0 verving die door een permanent draaiende C++-zoekkern, voegde een eersteklas Python-shell toe, liet zoeken werken zonder dat Zotero draait, en verhoogde het realistische plafond van "een paar honderd papers" naar 10,000+ PDF's. Het oude artikel staat nog online als historische referentie.

Aan de slag

npx @docsagent/mcp-zotero start

Dat ene commando verandert uw Zotero-bibliotheek in een privé, millisecondensnelle kennisbank voor welke AI-agent u al gebruikt. De installatienotities, toolschema's en volledige configuratiereferentie staan in de docsagent-repository, en meer achtergrond vindt u op de MCP-serverpagina.

Wilt u dezelfde engine in Zotero zelf — in-app chat, AutoPilot-batchlezen, lokale LLM's? Bekijk de vergelijking van Zotero AI-plugins en PapersGPT. Gebruikers die in de terminal werken, lezen ook de Zotero CLI-gids.