Zotero MCP Server: senza dover aprire Zotero, ricerca su 10,000 PDF in ~20 ms

Q: Il server Zotero MCP supporta Python oltre a JavaScript?

Sì. Ci sono due shell con funzionalità equivalenti: @docsagent/mcp-zotero su npm per gli utenti JavaScript/Node e docsagent-mcp-zotero su PyPI per Python 3.10+. Entrambe espongono gli stessi 8 strumenti con gli stessi schemi, codici di errore e gate di scrittura, e entrambe gestiscono lo stesso nucleo C++ incluso.

Se hai provato un server Zotero MCP di prima generazione, ricordi il rituale: Zotero doveva essere aperto, l'API locale doveva essere abilitata e ogni query percorreva la tua libreria un record di metadati alla volta. Va bene per una demo. Non va bene quando la tua libreria contiene 5,000 PDF e un agente lancia venti ricerche prima che tu finisca di scrivere una frase.

Il nuovo Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, rilasciato il 21 settembre 2026 — è una macchina diversa. Offre due shell (JavaScript e Python) sopra un nucleo di ricerca C++ nativo residente che legge direttamente la directory dati di Zotero. La ricerca funziona senza aprire Zotero, e librerie di 10,000+ PDF diventano una base di conoscenza a livello di millisecondi per Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline o qualsiasi altro client MCP.

Questa è la guida alla nuova versione: cosa è cambiato, come installarla in entrambi i runtime, gli 8 strumenti che il tuo agente riceve e i numeri di benchmark per librerie davvero grandi.

Novità di Zotero MCP Server 4.0

Due shell, un nucleo. Lo stesso contratto di strumenti è disponibile come pacchetto TypeScript su npm (@docsagent/mcp-zotero) e come pacchetto Python su PyPI (docsagent-mcp-zotero). Scegli il runtime che il tuo stack già utilizza: strumenti, schemi, codici di errore e gate di scrittura sono identici.
Non serve avviare Zotero. Il nucleo in C++ legge ~/Zotero/zotero.sqlite e la directory storage/ direttamente, quindi l'indicizzazione e la ricerca continuano a funzionare con Zotero chiuso — o anche su una macchina dove Zotero non è mai stato installato.
Un servizio residente, non un sottoprocesso per chiamata. Il nucleo gira in background su http://127.0.0.1:23120/rpc, ricostruisce il suo indice man mano che la tua libreria cambia e resta caldo tra i riavvii del client MCP. Il tuo agente non paga mai il costo di un avvio a freddo.
Pensato per librerie grandi. Ricerca full-text BM25 con indice invertito + ranking dei passaggi su 1,000+ PDF a ~15 ms, con un'impronta di memoria nell'ordine delle centinaia di MB invece che dei gigabyte.
8 strumenti MCP (5 di lettura + 3 di scrittura) con argomenti validati da schema JSON, budget di token, deduplicazione dei risultati e un gate di sicurezza in scrittura a tre livelli.
Due trasporti. stdio per i client MCP locali; Streamable HTTP (/mcp) con controlli sull'origine, autenticazione tramite API key o OAuth 2.0 (RFC 7662) e RBAC per richiesta quando lo distribuisci in remoto.
Un solo file di configurazione. ~/.docsagent/config.json è condiviso dalla shell JS, dalla shell Python e dal nucleo C++.

Come funziona: due shell su un unico nucleo nativo

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)

La separazione conta. La shell è sottile: contiene gli schemi degli strumenti, valida gli argomenti, applica i budget di token e non tocca mai i tuoi file Zotero. Il nucleo fa il lavoro pesante in C++, ed è per questo che lo stesso motore serve sia il pacchetto npm sia quello PyPI con un comportamento identico byte per byte.

Avvio rapido: collega Zotero al tuo agente IA in 3 passi

Opzione A — JavaScript / npm

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

Poi aggiungi il server alle impostazioni del tuo client MCP (Claude Desktop, Cursor, Cline, Qwen Code, …):

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

Opzione 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

Poi registra la shell Python allo stesso modo:

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

Riavvia il client MCP e chiedigli qualcosa come "Cosa dice la mia libreria Zotero sul degrado delle batterie nelle celle agli ioni di sodio?" — l'agente chiama search, riceve passaggi ordinati con BM25 e citazioni zotero:KEY, e risponde dai tuoi PDF invece che dal web aperto.

Entrambe le CLI espongono anche i comandi del ciclo di vita del nucleo — start, stop, restart, status (Python li esegue sotto un sottocomando core, cioè docsagent-mcp-zotero core restart) — più --transport streamable-http quando vuoi servire /mcp sulla rete.

Gli 8 strumenti che il tuo agente può chiamare

Strumento	Tipo	Cosa fa
`list_sources`	lettura	Tutte le fonti ricercabili, con capacità e conteggi dei documenti. Chiama questo per primo.
`search`	lettura	Ricerca su tutta la libreria tra item, annotazioni o note; profondità `ids` / `snippets` / `full`, filtri per tag, intervallo di anni, tipo di item, autori e collezioni.
`get_content`	lettura	Legge una voce come passaggi ordinati per pertinenza alla query (`k`) o come testo completo con paginazione a offset.
`get_metadata`	lettura	Metadati, abstract, annotazioni, note e citazioni (BibTeX / CSL-JSON / formattate).
`list_library`	lettura	Sfoglia collezioni, item, tag, ricerche salvate e note autonome.
`import_item`	scrittura	Importa PDF locali o risolve DOI / ISBN / arXiv ID, con classificazione automatica opzionale nelle collezioni.
`add_note`	scrittura	Scrive una nota in Markdown su un item come nota figlia di Zotero, con rollback.
`batch_modify`	scrittura	Aggiunge o rimuove collezioni o tag in blocco su un massimo di 200 item.

Gli strumenti di scrittura non vengono registrati affatto a meno che tu non imposti enableWrites: true. Anche in quel caso, una chiamata non confermata restituisce un'anteprima e non consuma quota, le scritture confermate sono limitate per frequenza (30/hour per impostazione predefinita) e qualsiasi batch_modify oltre 20 item torna con requiresConfirmation. Un agente può leggere la tua libreria tutto il giorno; non può riscriverla in silenzio.

Prestazioni: 10,000 PDF, 42 GB, indicizzati in ~7 minuti

Il nucleo di questo server MCP è lo stesso motore di indicizzazione e recupero dietro al benchmark di ricerca di PapersGPT. Numeri da un'installazione Zotero reale:

Dimensione libreria	Dati grezzi	Costruzione indice	Tempo medio di query	Memoria (RSS)	Dimensione indice
1,000 PDF	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000 PDF	42 GB	421 s (7 m 01 s)	19.5 ms	2.21 GB	901 MB

Su una configurazione volutamente modesta — 4 core / 8 GB di RAM — l'indicizzazione di 1,506 PDF (4.5 GB) ha richiesto 141 secondi mentre il processo occupava 227 MB di memoria, con un recupero medio di ~15 ms. Il pattern che conta:

L'indicizzazione scala in modo approssimativamente lineare. Dieci volte i PDF, dieci volte il tempo di costruzione — e lo paghi una volta per ogni nuovo documento, non per ogni domanda.
Il recupero resta piatto. 13 ms con 1,000 articoli, 19.5 ms con 10,000. Aggiungere articoli non rallenta il tuo agente.
La memoria resta contenuta. Lo scaricamento automatico mantiene una libreria da 42 GB ricercabile entro circa 2 GB di RAM.
Tutto è offline. Nessuna chiamata al cloud per l'indicizzazione o il recupero, quindi funziona in aereo, in una rete di laboratorio blindata o sotto embargo.

Perché "non serve avviare Zotero" cambia il flusso di lavoro

I server Zotero MCP classici sono wrapper sottili attorno alla API locale di Zotero (http://localhost:23119/api): senza processo Zotero, niente risposte. Quella singola dipendenza condiziona tutto — non puoi cercare nella tua libreria da un container, da una macchina di sviluppo remota, da uno script headless o da una sessione SSH; non puoi cercare mentre Zotero è in fase di sincronizzazione; e ogni chiamata è un round-trip di richiesta invece di una lookup sull'indice.

Poiché il nucleo di DocsAgent legge il database direttamente, la metà "lettura" del flusso di lavoro si disaccoppia dall'app Zotero:

	Server Zotero MCP basati su API	Zotero MCP Server 4.0
Zotero deve essere in esecuzione per cercare	Sì	No
Backend di ricerca	Chiamate alla API locale di Zotero	Indice nativo C++ BM25 + passaggi
Latenza di query con 10,000 PDF	Da centinaia di ms a secondi	~20 ms
Runtime	Di solito uno	JavaScript + Python
Trasporto remoto / HTTP	Raro	Streamable HTTP con autenticazione + RBAC
Sicurezza in scrittura	Di solito manuale	Gate a 3 livelli + limite di frequenza

Un'avvertenza onesta: le scritture passano comunque attraverso la API locale di Zotero, così che Zotero resti la fonte di verità della tua libreria. Se vuoi che l'agente importi PDF, aggiunga note o rietichettizzi item, Zotero deve essere in esecuzione per quello specifico passaggio. Indicizzazione, ricerca e lettura non lo richiedono mai.

Casi d'uso: cosa fanno davvero i ricercatori con questo strumento

Ricerca nell'editor con Claude Code o Cursor. Scrivi il tuo articolo e lascia che l'agente estragga passaggi, abstract e BibTeX direttamente dalla tua libreria mentre digiti — senza copia-incolla, senza schede del browser.
Triage della letteratura da terminale con Codex o Gemini CLI. "Trova tutti gli articoli della mia libreria che riportano un'efficienza di conversione di potenza superiore al 20% e aggiungili alla collezione Perovskite" — search seguito da batch_modify.
Lettura offline. In aereo o sul campo, l'indice risponde alle query localmente; non serve la rete.
Librerie di gruppo. Punta zoteroGroups alle librerie condivise del tuo laboratorio e cercale insieme alla tua collezione personale.
Skill per agenti. Il progetto pubblica anche un SKILL.md portabile, così gli agenti che supportano le skill possono imparare il flusso cerca-e-cita invece di indovinare gli argomenti degli strumenti.

Privacy e sicurezza

I tuoi PDF non lasciano mai la tua macchina: indicizzazione e recupero sono al 100% locali e nessun documento viene inviato a servizi cloud. Quando abiliti deliberatamente le scritture, queste sono controllate da gate, visualizzabili in anteprima, limitate per frequenza e reversibili. Quando esponi deliberatamente il server via HTTP, ottieni controlli sull'origine, autenticazione tramite token e RBAC per richiesta invece di una porta aperta.

Domande frequenti

Devo tenere Zotero in esecuzione perché il server MCP funzioni?

No — per cercare e leggere. Il nucleo legge direttamente la tua directory dati di Zotero (zotero.sqlite e storage/), quindi indicizzazione e ricerca funzionano con Zotero chiuso, e persino su una macchina dove l'app desktop di Zotero non è in esecuzione. Solo i tre strumenti di scrittura (importare item, aggiungere note, modifiche in blocco di tag/collezioni) passano dalla API locale di Zotero, quindi per quelli Zotero deve essere aperto.

Il server Zotero MCP supporta Python oltre a JavaScript?

Sì. Ci sono due shell con funzionalità equivalenti: @docsagent/mcp-zotero su npm per gli utenti JavaScript/Node e docsagent-mcp-zotero su PyPI per Python 3.10+. Entrambe espongono gli stessi 8 strumenti con gli stessi schemi, codici di errore e gate di scrittura, e entrambe gestiscono lo stesso nucleo C++ incluso.

Quanto può essere grande una libreria Zotero gestibile?

Librerie con migliaia di PDF sono la norma: 1,000 PDF (4.2 GB) si indicizzano in circa 52 secondi e si interrogano in ~13 ms; 10,000 PDF (42 GB) si indicizzano in circa 7 minuti e si interrogano in ~19.5 ms. Il tempo di costruzione dell'indice cresce in modo approssimativamente lineare con la dimensione della libreria, mentre la latenza delle query resta essenzialmente costante.

La mia libreria Zotero viene caricata da qualche parte?

No. Il nucleo costruisce e serve il suo indice interamente sulla tua macchina, e la ricerca non richiede accesso alla rete. Nulla dei tuoi articoli viene inviato a PapersGPT o a terzi.

L'agente IA può modificare la mia libreria Zotero?

Solo se glielo permetti. Gli strumenti di scrittura non vengono registrati a meno che enableWrites non sia impostato su true; le chiamate non confermate restituiscono un'anteprima; le scritture confermate sono limitate per frequenza (30/hour per impostazione predefinita); e i lotti multi-item superiori a 20 item richiedono una conferma esplicita.

Quali client IA sono supportati?

Qualsiasi client MCP. Il progetto documenta Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI e Qwen Code, e fornisce un trasporto Streamable HTTP per i client che si connettono in remoto invece che via stdio.

In cosa è diverso dalla precedente configurazione MCP di PapersGPT?

La configurazione precedente era un ponte monouso costruito attorno alla API locale di Zotero. La versione 4.0 l'ha sostituita con un nucleo di ricerca C++ residente, ha aggiunto una shell Python di primo livello, ha fatto funzionare la ricerca senza Zotero in esecuzione e ha alzato il tetto realistico da "qualche centinaio di articoli" a 10,000+ PDF. Il testo precedente è ancora online come riferimento storico.

Per iniziare

npx @docsagent/mcp-zotero start

Quel singolo comando trasforma la tua libreria Zotero in una base di conoscenza privata e velocissima per l'agente IA che già usi. Le note di configurazione, gli schemi degli strumenti e il riferimento completo della configurazione sono nel repository docsagent, e c'è ulteriore contesto nella pagina del server MCP.

Vuoi lo stesso motore dentro Zotero stesso — chat in-app, lettura in batch con AutoPilot, LLM locali? Vedi il confronto dei plugin IA per Zotero e PapersGPT. Chi preferisce il terminale dovrebbe leggere anche la guida a Zotero CLI.