Zotero MCP Server: Zotero muss nicht geöffnet werden, Suche in 10,000 PDFs in ~20 ms

Q: Unterstützt der Zotero MCP-Server Python genauso wie JavaScript?

Ja. Es gibt zwei funktionsgleiche Shells: @docsagent/mcp-zotero auf npm für JavaScript/Node-Nutzer und docsagent-mcp-zotero auf PyPI für Python 3.10+. Beide stellen dieselben 8 Tools mit denselben Schemas, Fehlercodes und demselben Write-Gate bereit, und beide verwalten denselben gebündelten C++-Kern.

Wenn Sie einen Zotero MCP-Server der ersten Generation ausprobiert haben, erinnern Sie sich an das Ritual: Zotero musste geöffnet sein, die lokale API musste aktiviert werden, und jede Abfrage kroch Metadatensatz für Metadatensatz durch Ihre Bibliothek. Für eine Demo ist das in Ordnung. Es ist nicht in Ordnung, wenn Ihre Bibliothek 5,000 PDFs enthält und ein Agent zwanzig Suchen startet, bevor Sie einen Satz zu Ende getippt haben.

Der neue Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, veröffentlicht am 21. September 2026 — ist eine andere Maschine. Er liefert zwei Shells (JavaScript und Python) auf einem dauerhaft laufenden nativen C++-Suchkern, der Ihr Zotero-Datenverzeichnis direkt liest. Die Suche funktioniert ohne Zotero zu öffnen, und Bibliotheken mit 10,000+ PDFs werden zu einer Wissensbasis auf Millisekundenebene für Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline oder jeden anderen MCP-Client.

Dies ist der Leitfaden zur neuen Version: was sich geändert hat, wie Sie sie in beiden Runtimes installieren, die 8 Tools, die Ihr Agent erhält, und die Benchmark-Zahlen für wirklich große Bibliotheken.

Was ist neu in Zotero MCP Server 4.0

Zwei Shells, ein Kern. Derselbe Tool-Vertrag ist als TypeScript-Paket auf npm (@docsagent/mcp-zotero) und als Python-Paket auf PyPI (docsagent-mcp-zotero) verfügbar. Wählen Sie die Runtime, die Ihr Stack bereits nutzt — Tools, Schemas, Fehlercodes und das Write-Gate sind identisch.
Kein Start von Zotero nötig. Der C++-Kern liest ~/Zotero/zotero.sqlite plus das Verzeichnis storage/ direkt, sodass Indexierung und Suche weiter funktionieren, während Zotero geschlossen ist — oder auf diesem Rechner nie installiert wurde.
Ein dauerhaft laufender Dienst, kein Subprozess pro Aufruf. Der Kern läuft im Hintergrund auf http://127.0.0.1:23120/rpc, baut seinen Index neu auf, wenn sich Ihre Bibliothek ändert, und bleibt über Neustarts des MCP-Clients hinweg warm. Ihr Agent zahlt nie einen Kaltstart-Aufschlag.
Für große Bibliotheken gebaut. Invertierter Index mit BM25-Volltextsuche + Passage-Ranking über 1,000+ PDFs bei ~15 ms, mit einem Speicherbedarf im niedrigen dreistelligen MB-Bereich statt in Gigabytes.
8 MCP-Tools (5 lesend + 3 schreibend) mit JSON-Schema-validierten Argumenten, Token-Budgets, Ergebnis-Deduplizierung und einem dreischichtigen Sicherheits-Gate für Schreibvorgänge.
Zwei Transporte. stdio für lokale MCP-Clients; Streamable HTTP (/mcp) mit Origin-Prüfungen, API-Key- oder OAuth 2.0-(RFC 7662-)Authentifizierung und RBAC pro Anfrage, wenn Sie ihn remote bereitstellen.
Eine Konfigurationsdatei. ~/.docsagent/config.json wird von der JS-Shell, der Python-Shell und dem C++-Kern gemeinsam genutzt.

Wie es funktioniert: zwei Shells über einem nativen 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)

Die Aufteilung ist entscheidend. Die Shell ist dünn — sie hält die Tool-Schemas, validiert Argumente, erzwingt Token-Budgets und berührt Ihre Zotero-Dateien nie. Der Kern erledigt die Schwerarbeit in C++, weshalb dieselbe Engine sowohl das npm- als auch das PyPI-Paket mit byte-identischem Verhalten bedient.

Schnellstart: Verbinden Sie Zotero in 3 Schritten mit Ihrem KI-Agenten

Option A — JavaScript / npm

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

Fügen Sie den Server dann zu den Einstellungen Ihres MCP-Clients hinzu (Claude Desktop, Cursor, Cline, Qwen Code, …):

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

Option 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

Registrieren Sie die Python-Shell dann auf dieselbe Weise:

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

Starten Sie Ihren MCP-Client neu und fragen Sie ihn etwas wie "Was sagt meine Zotero-Bibliothek über Batteriedegradation in Natrium-Ionen-Zellen?" — der Agent ruft search auf, erhält BM25-gerankte Passagen mit zotero:KEY-Zitaten und antwortet aus Ihren PDFs statt aus dem offenen Web.

Beide CLIs bieten außerdem Befehle für den Lebenszyklus des Kerns — start, stop, restart, status (Python führt sie unter einem core-Unterbefehl aus, also docsagent-mcp-zotero core restart) — plus --transport streamable-http, wenn Sie /mcp über das Netzwerk bereitstellen möchten.

Die 8 Tools, die Ihr Agent aufrufen kann

Tool	Typ	Was es tut
`list_sources`	Lesen	Jede durchsuchbare Quelle mit Fähigkeiten und Dokumentanzahl. Rufen Sie dies zuerst auf.
`search`	Lesen	Bibliotheksübergreifende Suche über Elemente, Anmerkungen oder Notizen; Tiefe `ids` / `snippets` / `full`, Filter für Tags, Jahresbereich, Elementtyp, Autoren, Sammlungen.
`get_content`	Lesen	Einen Eintrag als abfrage-gerankte Passagen (`k`) oder als Volltext mit Offset-Paginierung lesen.
`get_metadata`	Lesen	Metadaten, Abstract, Anmerkungen, Notizen und Zitate (BibTeX / CSL-JSON / formatiert).
`list_library`	Lesen	Sammlungen, Elemente, Tags, gespeicherte Suchen und eigenständige Notizen durchsuchen.
`import_item`	Schreiben	Lokale PDFs importieren oder DOI / ISBN / arXiv-IDs auflösen, mit optionaler automatischer Sammlungsklassifizierung.
`add_note`	Schreiben	Eine Markdown-Notiz als Zotero-Kindnotiz zu einem Element zurückschreiben, mit Rollback.
`batch_modify`	Schreiben	Sammlungen oder Tags für bis zu 200 Elemente massenhaft hinzufügen/entfernen.

Write-Tools werden überhaupt nicht registriert, es sei denn, Sie setzen enableWrites: true. Selbst dann gibt ein unbestätigter Aufruf eine Vorschau zurück und verbraucht kein Kontingent, bestätigte Schreibvorgänge sind ratenbegrenzt (Standard: 30/hour), und jedes batch_modify über 20 Elemente kommt mit requiresConfirmation zurück. Ein Agent kann Ihre Bibliothek den ganzen Tag lesen; er kann sie nicht still und leise umschreiben.

Leistung: 10,000 PDFs, 42 GB, indexiert in ~7 Minuten

Der Kern in diesem MCP-Server ist dieselbe Indexierungs- und Retrieval-Engine, die hinter PapersGPTs Such-Benchmark steht. Zahlen aus einer echten Zotero-Installation:

Bibliotheksgröße	Rohdaten	Indexaufbau	Durchschn. Abfragezeit	Speicher (RSS)	Indexgröße
1,000 PDFs	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000 PDFs	42 GB	421 s (7 m 01 s)	19.5 ms	2.21 GB	901 MB

Auf einem bewusst bescheidenen Setup — 4 Kerne / 8 GB RAM — dauerte die Indexierung von 1,506 PDFs (4.5 GB) 141 Sekunden, während der Prozess 227 MB Speicher belegte, bei durchschnittlichem Abruf von ~15 ms. Das Muster, auf das es ankommt:

Die Indexierung skaliert grob linear. Zehnmal so viele PDFs, zehnmal so lange Build-Zeit — und Sie zahlen sie einmal pro neuem Dokument, nicht pro Frage.
Der Abruf bleibt konstant. 13 ms bei 1,000 Arbeiten, 19.5 ms bei 10,000. Zusätzliche Arbeiten machen Ihren Agenten nicht langsamer.
Der Speicher bleibt bescheiden. Automatisches Auslagern hält eine 42-GB-Bibliothek in etwa 2 GB RAM durchsuchbar.
Alles ist offline. Keine Cloud-Aufrufe für Indexierung oder Abruf, also funktioniert es im Flugzeug, in einem abgeschotteten Labornetzwerk oder unter einer Embargo-Sperre.

Warum "kein Start von Zotero nötig" den Workflow verändert

Klassische Zotero MCP-Server sind dünne Wrapper um die Zotero local API (http://localhost:23119/api): kein Zotero-Prozess, keine Antworten. Diese einzige Abhängigkeit prägt alles — Sie können Ihre Bibliothek nicht aus einem Container, einer entfernten Dev-Box, einem headless Skript oder einer SSH-Sitzung durchsuchen; Sie können nicht suchen, während Zotero mitten in einer Synchronisierung steckt; und jeder Aufruf ist ein Request-Roundtrip statt eines Index-Lookups.

Weil der DocsAgent-Kern die Datenbank direkt liest, ist die lesende Hälfte des Workflows von der Zotero-App entkoppelt:

	API-basierte Zotero MCP-Server	Zotero MCP Server 4.0
Zotero muss laufen, um zu suchen	Ja	Nein
Such-Backend	Zotero local API-Aufrufe	Nativer C++-BM25- + Passage-Index
Abfragelatenz bei 10,000 PDFs	Hunderte von ms bis Sekunden	~20 ms
Runtimes	Meist eine	JavaScript + Python
Remote- / HTTP-Transport	Selten	Streamable HTTP mit Auth + RBAC
Schreibsicherheit	Meist manuell	3-Schichten-Gate + Ratenbegrenzung

Eine ehrliche Einschränkung: Schreibvorgänge laufen weiterhin über Zoteros eigene lokale API, damit Zotero die Quelle der Wahrheit für Ihre Bibliothek bleibt. Wenn der Agent PDFs importieren, Notizen hinzufügen oder Elemente neu taggen soll, muss Zotero für diesen speziellen Schritt laufen. Bei Indexierung, Suche und Lesen ist das nie der Fall.

Anwendungsfälle: Was Forschende tatsächlich damit machen

Recherche im Editor mit Claude Code oder Cursor. Schreiben Sie Ihre Arbeit und lassen Sie den Agenten Passagen, Abstracts und BibTeX direkt aus Ihrer eigenen Bibliothek ziehen, während Sie tippen — kein Copy-Paste, keine Browser-Tabs.
Literatur-Triage im Terminal mit Codex oder Gemini CLI. "Finde jede Arbeit in meiner Bibliothek, die einen Wirkungsgrad der Leistungsumwandlung über 20% berichtet, und füge sie der Sammlung Perovskite hinzu" — search gefolgt von batch_modify.
Offline lesen. Im Flugzeug oder im Feld beantwortet der Index Abfragen lokal; nichts braucht ein Netzwerk.
Gruppenbibliotheken. Richten Sie zoteroGroups auf die geteilten Bibliotheken Ihres Labors und durchsuchen Sie sie zusammen mit Ihrer persönlichen Sammlung.
Agent-Skills. Das Projekt veröffentlicht außerdem eine portable SKILL.md, damit Agenten, die Skills unterstützen, den Workflow "erst suchen, dann zitieren" lernen können, statt bei Tool-Argumenten zu raten.

Datenschutz und Sicherheit

Ihre PDFs verlassen nie Ihren Rechner: Indexierung und Abruf sind zu 100 % lokal, und keine Dokumente werden an einen Cloud-Dienst gesendet. Wenn Sie Schreibvorgänge bewusst aktivieren, sind sie durch ein Gate geschützt, als Vorschau sichtbar, ratenbegrenzt und umkehrbar. Wenn Sie den Server bewusst über HTTP exponieren, erhalten Sie Origin-Prüfungen, Token-Auth und RBAC pro Anfrage statt eines offenen Ports.

Häufig gestellte Fragen

Muss Zotero laufen, damit der MCP-Server funktioniert?

Nein — für Suche und Lesen. Der Kern liest Ihr Zotero-Datenverzeichnis (zotero.sqlite und storage/) direkt, sodass Indexierung und Suche bei geschlossenem Zotero funktionieren, und sogar auf einem Rechner, auf dem die Zotero-Desktop-App nicht läuft. Nur die drei Write-Tools (Elemente importieren, Notizen hinzufügen, Massenbearbeitung von Tags/Sammlungen) laufen über Zoteros lokale API, Zotero muss dafür also geöffnet sein.

Unterstützt der Zotero MCP-Server Python genauso wie JavaScript?

Ja. Es gibt zwei funktionsgleiche Shells: @docsagent/mcp-zotero auf npm für JavaScript/Node-Nutzer und docsagent-mcp-zotero auf PyPI für Python 3.10+. Beide stellen dieselben 8 Tools mit denselben Schemas, Fehlercodes und demselben Write-Gate bereit, und beide verwalten denselben gebündelten C++-Kern.

Wie große Zotero-Bibliotheken kann er bewältigen?

Bibliotheken in der Größenordnung Tausender PDFs sind Routine: 1,000 PDFs (4.2 GB) werden in etwa 52 Sekunden indexiert und in ~13 ms abgefragt; 10,000 PDFs (42 GB) werden in etwa 7 Minuten indexiert und in ~19.5 ms abgefragt. Die Indexaufbauzeit wächst grob linear mit der Bibliotheksgröße, während die Abfragelatenz praktisch konstant bleibt.

Wird meine Zotero-Bibliothek irgendwohin hochgeladen?

Nein. Der Kern baut und bedient seinen Index vollständig auf Ihrem Rechner, und die Suche benötigt keinen Netzwerkzugriff. Nichts an Ihren Arbeiten wird an PapersGPT oder Dritte gesendet.

Kann der KI-Agent meine Zotero-Bibliothek verändern?

Nur wenn Sie es erlauben. Write-Tools werden nicht registriert, es sei denn, enableWrites ist auf true gesetzt; unbestätigte Aufrufe geben eine Vorschau zurück; bestätigte Schreibvorgänge sind ratenbegrenzt (standardmäßig 30/hour); und Batches mit mehr als 20 Elementen erfordern eine ausdrückliche Bestätigung.

Welche KI-Clients werden unterstützt?

Jeder MCP-Client. Das Projekt dokumentiert Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI und Qwen Code und liefert einen Streamable-HTTP-Transport für Clients, die sich remote statt über stdio verbinden.

Wie unterscheidet sich das vom älteren PapersGPT MCP-Setup?

Das ältere Setup war eine zweckgebundene Brücke rund um die Zotero local API. Version 4.0 hat sie durch einen dauerhaft laufenden C++-Suchkern ersetzt, eine erstklassige Python-Shell hinzugefügt, die Suche ohne laufendes Zotero ermöglicht und die realistische Obergrenze von "ein paar hundert Arbeiten" auf 10,000+ PDFs angehoben. Die alte Beschreibung ist noch als historische Referenz online.

Erste Schritte

npx @docsagent/mcp-zotero start

Dieser eine Befehl verwandelt Ihre Zotero-Bibliothek in eine private, millisekundenschnelle Wissensbasis für den KI-Agenten, den Sie bereits nutzen. Die Setup-Hinweise, Tool-Schemas und die vollständige Konfigurationsreferenz finden Sie im docsagent-Repository, und mehr Hintergrund gibt es auf der MCP-Server-Seite.

Möchten Sie dieselbe Engine direkt in Zotero — In-App-Chat, AutoPilot-Batch-Lesen, lokale LLMs? Sehen Sie sich den Vergleich der Zotero-KI-Plugins und PapersGPT an. Terminal-Fans sollten außerdem den Zotero CLI-Leitfaden lesen.