Zotero MCP Server: bez konieczności otwierania Zotero, przeszukiwanie 10,000 PDF-ów w ~20 ms

Q: Czy serwer Zotero MCP obsługuje Python tak samo jak JavaScript?

Tak. Istnieją dwie równoważne funkcjonalnie powłoki: @docsagent/mcp-zotero w npm dla użytkowników JavaScript/Node oraz docsagent-mcp-zotero w PyPI dla Python 3.10+. Obie udostępniają te same 8 narzędzi z tymi samymi schematami, kodami błędów i bramką zapisu, a obie zarządzają tym samym dołączonym rdzeniem C++.

Jeśli próbowałeś serwera Zotero MCP pierwszej generacji, pamiętasz ten rytuał: Zotero musiało być otwarte, lokalne API musiało być włączone, a każde zapytanie pełzło przez Twoją bibliotekę rekord po rekordzie metadanych. Do demo to wystarczy. Nie wystarczy, gdy Twoja biblioteka liczy 5,000 PDF-ów, a agent odpala dwadzieścia wyszukiwań, zanim skończysz pisać zdanie.

Nowy Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, wydany 21 września 2026 — to inna maszyna. Dostarcza dwie powłoki (JavaScript i Python) na stale działającym natywnym rdzeniu wyszukiwania w C++, który czyta katalog danych Zotero bezpośrednio. Wyszukiwanie działa bez otwierania Zotero, a biblioteki z 10,000+ PDF-ów stają się bazą wiedzy o opóźnieniu milisekundowym dla Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline lub dowolnego innego klienta MCP.

To przewodnik po nowej wersji: co się zmieniło, jak ją zainstalować w obu runtime'ach, jakie 8 narzędzi otrzymuje Twój agent i jakie są wyniki benchmarków dla naprawdę dużych bibliotek.

Co nowego w Zotero MCP Server 4.0

Dwie powłoki, jeden rdzeń. Ten sam kontrakt narzędzi jest dostępny jako pakiet TypeScript w npm (@docsagent/mcp-zotero) i jako pakiet Python w PyPI (docsagent-mcp-zotero). Wybierz runtime, którego już używa Twój stack — narzędzia, schematy, kody błędów i bramka zapisu są identyczne.
Nie trzeba uruchamiać Zotero. Rdzeń C++ czyta ~/Zotero/zotero.sqlite oraz katalog storage/ bezpośrednio, więc indeksowanie i wyszukiwanie działają dalej, gdy Zotero jest zamknięte — albo nigdy nie zostało zainstalowane na tej maszynie.
Stała usługa, nie podproces na każde wywołanie. Rdzeń działa w tle pod http://127.0.0.1:23120/rpc, przebudowuje indeks wraz ze zmianami w Twojej bibliotece i pozostaje rozgrzany między restartami klienta MCP. Twój agent nigdy nie płaci podatku od zimnego startu.
Zbudowany dla dużych bibliotek. Indeks odwrócony z wyszukiwaniem pełnotekstowym BM25 + rankingiem fragmentów po 1,000+ PDF-ach w ~15 ms, ze zużyciem pamięci w niskich setkach MB zamiast gigabajtów.
8 narzędzi MCP (5 odczytu + 3 zapisu) z argumentami walidowanymi przez schemat JSON, budżetami tokenów, deduplikacją wyników i trójwarstwową bramką bezpieczeństwa zapisu.
Dwa transporty. stdio dla lokalnych klientów MCP; Streamable HTTP (/mcp) z kontrolami origin, uwierzytelnianiem API-key lub OAuth 2.0 (RFC 7662) oraz RBAC na żądanie, gdy wdrażasz go zdalnie.
Jeden plik konfiguracyjny. ~/.docsagent/config.json jest współdzielony przez powłokę JS, powłokę Python i rdzeń C++.

Jak to działa: dwie powłoki nad jednym natywnym rdzeniem

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)

Podział ma znaczenie. Powłoka jest cienka — trzyma schematy narzędzi, waliduje argumenty, egzekwuje budżety tokenów i nigdy nie dotyka Twoich plików Zotero. Rdzeń wykonuje ciężką pracę w C++, dlatego ten sam silnik obsługuje zarówno pakiet npm, jak i PyPI, zachowując się identycznie.

Szybki start: połącz Zotero ze swoim agentem AI w 3 krokach

Opcja A — JavaScript / npm

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

Następnie dodaj serwer do ustawień swojego klienta MCP (Claude Desktop, Cursor, Cline, Qwen Code, …):

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

Opcja 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

Następnie zarejestruj powłokę Python w ten sam sposób:

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

Zrestartuj klienta MCP i zapytaj go na przykład "Co moja biblioteka Zotero mówi o degradacji baterii w ogniwach sodowo-jonowych?" — agent wywoła search, otrzyma fragmenty uszeregowane przez BM25 z cytowaniami zotero:KEY i odpowie z Twoich PDF-ów zamiast z otwartej sieci.

Oba CLI udostępniają też polecenia cyklu życia rdzenia — start, stop, restart, status (Python uruchamia je w podpoleceniu core, czyli docsagent-mcp-zotero core restart) — oraz --transport streamable-http, gdy chcesz serwować /mcp przez sieć.

8 narzędzi, które może wywołać Twój agent

Narzędzie	Typ	Co robi
`list_sources`	Odczyt	Każde przeszukiwalne źródło z możliwościami i liczbą dokumentów. Wywołaj to najpierw.
`search`	Odczyt	Wyszukiwanie między bibliotekami po elementach, adnotacjach lub notatkach; głębokość `ids` / `snippets` / `full`, filtry po tagach, zakresie lat, typie elementu, autorach, kolekcjach.
`get_content`	Odczyt	Odczytaj jeden wpis jako fragmenty uszeregowane według zapytania (`k`) lub pełny tekst ze stronicowaniem offsetowym.
`get_metadata`	Odczyt	Metadane, abstrakt, adnotacje, notatki i cytowania (BibTeX / CSL-JSON / sformatowane).
`list_library`	Odczyt	Przeglądaj kolekcje, elementy, tagi, zapisane wyszukiwania i samodzielne notatki.
`import_item`	Zapis	Importuj lokalne PDF-y lub rozwiązuj identyfikatory DOI / ISBN / arXiv, z opcjonalną automatyczną klasyfikacją kolekcji.
`add_note`	Zapis	Zapisz notatkę Markdown z powrotem do elementu jako notatkę podrzędną Zotero, z możliwością wycofania.
`batch_modify`	Zapis	Masowo dodawaj lub usuwaj kolekcje i tagi dla maksymalnie 200 elementów.

Narzędzia zapisu nie są w ogóle rejestrowane, dopóki nie ustawisz enableWrites: true. Nawet wtedy niepotwierdzone wywołanie zwraca podgląd i nie zużywa limitu, potwierdzone zapisy mają limit szybkości (domyślnie 30/hour), a każde batch_modify powyżej 20 elementów wraca z requiresConfirmation. Agent może czytać Twoją bibliotekę przez cały dzień; nie może jej po cichu przepisać.

Wydajność: 10,000 PDF-ów, 42 GB, indeks w ~7 minut

Rdzeń w tym serwerze MCP to ten sam silnik indeksowania i wyszukiwania, który stoi za benchmarkiem wyszukiwania PapersGPT. Liczby z prawdziwej instalacji Zotero:

Rozmiar biblioteki	Surowce danych	Budowa indeksu	Śr. czas zapytania	Pamięć (RSS)	Rozmiar indeksu
1,000 PDF-ów	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000 PDF-ów	42 GB	421 s (7 m 01 s)	19.5 ms	2.21 GB	901 MB

Na celowo skromnej konfiguracji — 4 rdzenie / 8 GB RAM — indeksowanie 1,506 PDF-ów (4.5 GB) zajęło 141 sekund, a proces utrzymywał 227 MB pamięci, przy średnim wyszukiwaniu ~15 ms. Wzorzec, który ma znaczenie:

Indeksowanie skaluje się w przybliżeniu liniowo. Dziesięć razy więcej PDF-ów, dziesięć razy dłuższa budowa — i płacisz za to raz na nowy dokument, a nie za każde pytanie.
Wyszukiwanie pozostaje płaskie. 13 ms przy 1,000 prac, 19.5 ms przy 10,000. Dodawanie prac nie spowalnia Twojego agenta.
Pamięć pozostaje skromna. Automatyczne odciążanie utrzymuje bibliotekę o rozmiarze 42 GB przeszukiwalną w około 2 GB RAM.
Wszystko działa offline. Żadnych wywołań chmurowych przy indeksowaniu ani wyszukiwaniu, więc działa w samolocie, w zamkniętej sieci laboratoryjnej czy w trakcie embargo.

Dlaczego "bez konieczności uruchamiania Zotero" zmienia workflow

Klasyczne serwery Zotero MCP to cienkie opakowania na lokalne API Zotero (http://localhost:23119/api): brak procesu Zotero, brak odpowiedzi. Ta jedna zależność kształtuje wszystko — nie możesz przeszukiwać biblioteki z kontenera, zdalnej maszyny deweloperskiej, skryptu headless ani sesji SSH; nie możesz szukać, gdy Zotero jest w trakcie synchronizacji; a każde wywołanie to rundka żądania, a nie odczyt z indeksu.

Ponieważ rdzeń DocsAgent czyta bazę danych bezpośrednio, czytająca połowa workflow jest oddzielona od aplikacji Zotero:

	Serwery Zotero MCP oparte na API	Zotero MCP Server 4.0
Zotero musi działać, aby szukać	Tak	Nie
Backend wyszukiwania	Wywołania lokalnego API Zotero	Natywny indeks C++ BM25 + fragmentów
Opóźnienie zapytania przy 10,000 PDF-ów	Od setek ms do sekund	~20 ms
Runtime'y	Zwykle jeden	JavaScript + Python
Transport zdalny / HTTP	Rzadko	Streamable HTTP z uwierzytelnianiem + RBAC
Bezpieczeństwo zapisu	Zwykle ręczne	Bramka 3-warstwowa + limit szybkości

Jedno szczere zastrzeżenie: zapisy nadal przechodzą przez własne lokalne API Zotero, aby Zotero pozostało źródłem prawdy dla Twojej biblioteki. Jeśli chcesz, by agent importował PDF-y, dodawał notatki lub zmieniał tagi elementów, Zotero musi działać na potrzeby tego konkretnego kroku. Indeksowanie, wyszukiwanie i czytanie — nigdy.

Zastosowania: co badacze naprawdę z tym robią

Badania w edytorze z Claude Code lub Cursor. Pisz swoją pracę i pozwól agentowi wyciągać fragmenty, abstrakty i BibTeX prosto z Twojej biblioteki, gdy piszesz — bez kopiowania i wklejania, bez kart przeglądarki.
Selekcja literatury w terminalu z Codex lub Gemini CLI. "Znajdź każdą pracę w mojej bibliotece, która podaje sprawność konwersji mocy powyżej 20%, i dodaj je do kolekcji Perovskite" — search, a następnie batch_modify.
Czytanie offline. W samolocie lub w terenie indeks odpowiada lokalnie; nic nie potrzebuje sieci.
Biblioteki grupowe. Wskaż zoteroGroups na współdzielone biblioteki Twojego laboratorium i przeszukuj je razem ze swoją kolekcją osobistą.
Umiejętności agentów. Projekt publikuje też przenośny SKILL.md, dzięki czemu agenci wspierający umiejętności mogą nauczyć się workflow "najpierw szukaj, potem cytuj", zamiast zgadywać argumenty narzędzi.

Prywatność i bezpieczeństwo

Twoje PDF-y nigdy nie opuszczają Twojej maszyny: indeksowanie i wyszukiwanie są w 100% lokalne, a żadne dokumenty nie są wysyłane do usługi chmurowej. Gdy świadomie włączysz zapisy, są one ograniczone bramką, mają podgląd, limit szybkości i są odwracalne. Gdy świadomie wystawisz serwer przez HTTP, dostajesz kontrole origin, uwierzytelnianie tokenem i RBAC na żądanie zamiast otwartego portu.

Najczęściej zadawane pytania

Czy muszę mieć uruchomione Zotero, aby serwer MCP działał?

Nie — jeśli chodzi o wyszukiwanie i czytanie. Rdzeń czyta katalog danych Zotero (zotero.sqlite i storage/) bezpośrednio, więc indeksowanie i wyszukiwanie działają przy zamkniętym Zotero, a nawet na maszynie, na której aplikacja desktopowa Zotero nie działa. Tylko trzy narzędzia zapisu (import elementów, dodawanie notatek, masowa edycja tagów i kolekcji) przechodzą przez lokalne API Zotero, więc dla nich Zotero musi być otwarte.

Czy serwer Zotero MCP obsługuje Python tak samo jak JavaScript?

Tak. Istnieją dwie równoważne funkcjonalnie powłoki: @docsagent/mcp-zotero w npm dla użytkowników JavaScript/Node oraz docsagent-mcp-zotero w PyPI dla Python 3.10+. Obie udostępniają te same 8 narzędzi z tymi samymi schematami, kodami błędów i bramką zapisu, a obie zarządzają tym samym dołączonym rdzeniem C++.

Jak dużą bibliotekę Zotero obsłuży?

Biblioteki liczące tysiące PDF-ów to rutyna: 1,000 PDF-ów (4.2 GB) indeksuje się w około 52 sekundy i przeszukuje w ~13 ms; 10,000 PDF-ów (42 GB) indeksuje się w około 7 minut i przeszukuje w ~19.5 ms. Czas budowy indeksu rośnie w przybliżeniu liniowo wraz z rozmiarem biblioteki, a opóźnienie zapytania pozostaje zasadniczo stałe.

Czy moja biblioteka Zotero jest gdzieś wysyłana?

Nie. Rdzeń buduje i obsługuje swój indeks w całości na Twojej maszynie, a wyszukiwanie nie wymaga dostępu do sieci. Nic z Twoich prac nie jest wysyłane do PapersGPT ani do osób trzecich.

Czy agent AI może modyfikować moją bibliotekę Zotero?

Tylko jeśli mu pozwolisz. Narzędzia zapisu nie są rejestrowane, dopóki enableWrites nie jest ustawione na true; niepotwierdzone wywołania zwracają podgląd; potwierdzone zapisy mają limit szybkości (domyślnie 30/hour); a partie powyżej 20 elementów wymagają wyraźnego potwierdzenia.

Którzy klienci AI są obsługiwani?

Każdy klient MCP. Projekt dokumentuje Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI i Qwen Code oraz dostarcza transport Streamable HTTP dla klientów, które łączą się zdalnie, a nie przez stdio.

Czym to się różni od starszej konfiguracji PapersGPT MCP?

Starsza konfiguracja była jednofunkcyjnym mostem zbudowanym wokół lokalnego API Zotero. Wersja 4.0 zastąpiła go stałym rdzeniem wyszukiwania w C++, dodała pełnoprawną powłokę Python, sprawiła, że wyszukiwanie działa bez uruchomionego Zotero, i podniosła realistyczny pułap z "kilkuset prac" do 10,000+ PDF-ów. Stary artykuł wciąż jest online jako odniesienie historyczne.

Pierwsze kroki

npx @docsagent/mcp-zotero start

To jedno polecenie zamienia Twoją bibliotekę Zotero w prywatną, błyskawiczną bazę wiedzy dla dowolnego agenta AI, którego już używasz. Notatki instalacyjne, schematy narzędzi i pełna dokumentacja konfiguracji znajdują się w repozytorium docsagent, a więcej kontekstu na stronie serwera MCP.

Chcesz ten sam silnik wewnątrz Zotero — czat w aplikacji, wsadowe czytanie AutoPilot, lokalne LLM-y? Zobacz porównanie wtyczek AI do Zotero i PapersGPT. Osoby pracujące w terminalu powinny też przeczytać przewodnik po Zotero CLI.