Zotero MCP Server : sans avoir besoin d'ouvrir Zotero, recherche dans 10,000 PDF en ~20 ms
Si vous avez essayé un serveur MCP Zotero de première génération, vous vous souvenez du rituel : Zotero devait être ouvert, l'API locale devait être activée, et chaque requête parcourait votre bibliothèque un enregistrement de métadonnées après l'autre. C'est acceptable pour une démo. Ça ne l'est plus quand votre bibliothèque contient 5,000 PDF et qu'un agent lance vingt recherches avant que vous ayez fini de taper une phrase.
Le nouveau Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, publié le 21 septembre 2026 — est une machine d'une autre nature. Il embarque deux shells (JavaScript et Python) au-dessus d'un cœur de recherche natif C++ résident qui lit directement votre répertoire de données Zotero. La recherche fonctionne sans ouvrir Zotero, et les bibliothèques de 10,000+ PDF deviennent une base de connaissances à l'échelle de la milliseconde pour Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline ou tout autre client MCP.
Voici le guide de cette nouvelle version : ce qui a changé, comment l'installer dans les deux environnements d'exécution, les 8 outils mis à disposition de votre agent et les chiffres de performance pour les bibliothèques réellement volumineuses.
Nouveautés de Zotero MCP Server 4.0
- Deux shells, un seul cœur. Le même contrat d'outils est disponible sous forme de paquet TypeScript sur npm (
@docsagent/mcp-zotero) et de paquet Python sur PyPI (docsagent-mcp-zotero). Choisissez l'environnement d'exécution que votre stack utilise déjà — les outils, les schémas, les codes d'erreur et le verrou d'écriture sont identiques. - Plus besoin de démarrer Zotero. Le cœur C++ lit directement
~/Zotero/zotero.sqliteainsi que le répertoirestorage/, si bien que l'indexation et la recherche continuent de fonctionner même quand Zotero est fermé — ou n'a jamais été installé sur cette machine. - Un service résident, pas un sous-processus par appel. Le cœur tourne en arrière-plan sur
http://127.0.0.1:23120/rpc, reconstruit son index au fil des modifications de votre bibliothèque et reste chaud entre deux redémarrages du client MCP. Votre agent ne paie jamais de taxe de démarrage à froid. - Conçu pour les grandes bibliothèques. Recherche plein texte BM25 par index inversé + classement de passages sur 1,000+ PDF en ~15 ms, avec une empreinte mémoire de quelques centaines de MB plutôt que de plusieurs gigaoctets.
- 8 outils MCP (5 en lecture + 3 en écriture) avec arguments validés par schéma JSON, budgets de tokens, déduplication des résultats et verrou de sécurité d'écriture à trois couches.
- Deux transports.
stdiopour les clients MCP locaux ; Streamable HTTP (/mcp) avec vérifications d'origine, authentification par clé d'API ou OAuth 2.0 (RFC 7662) et RBAC par requête lorsque vous le déployez à distance. - Un seul fichier de configuration.
~/.docsagent/config.jsonest partagé par le shell JS, le shell Python et le cœur C++.
Comment ça marche : deux shells au-dessus d'un cœur natif unique
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)
Cette séparation compte. Le shell est mince — il porte les schémas d'outils, valide les arguments, applique les budgets de tokens et ne touche jamais à vos fichiers Zotero. Le cœur fait le gros du travail en C++, et c'est pourquoi le même moteur sert à la fois le paquet npm et le paquet PyPI avec un comportement strictement identique.
Démarrage rapide : connectez Zotero à votre agent IA en 3 étapes
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
Ajoutez ensuite le serveur à la configuration de votre client MCP (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
Enregistrez ensuite le shell Python de la même manière :
{
"mcpServers": {
"docsagent-zotero": {
"command": "docsagent-mcp-zotero",
"args": []
}
}
}
Redémarrez votre client MCP et posez-lui une question du type « Que dit ma bibliothèque Zotero sur la dégradation des batteries dans les cellules sodium-ion ? » — l'agent appelle search, obtient des passages classés par BM25 avec des citations zotero:KEY et répond à partir de vos PDF plutôt que du web ouvert.
Les deux CLI exposent aussi les commandes de cycle de vie du cœur — start, stop, restart, status (Python les exécute sous une sous-commande core, soit docsagent-mcp-zotero core restart) — ainsi que --transport streamable-http lorsque vous voulez servir /mcp sur le réseau.
Les 8 outils que votre agent peut appeler
| Outil | Type | Ce qu'il fait |
|---|---|---|
list_sources |
read | Chaque source interrogeable, avec ses capacités et son nombre de documents. Appelez-le en premier. |
search |
read | Recherche inter-bibliothèques sur les éléments, annotations ou notes ; profondeur ids / snippets / full, filtres par balises, plage d'années, type d'élément, auteurs, collections. |
get_content |
read | Lire une entrée sous forme de passages classés selon la requête (k) ou en texte intégral avec pagination par offset. |
get_metadata |
read | Métadonnées, résumé, annotations, notes et citations (BibTeX / CSL-JSON / formatées). |
list_library |
read | Parcourir les collections, éléments, balises, recherches enregistrées et notes autonomes. |
import_item |
write | Importer des PDF locaux ou résoudre des identifiants DOI / ISBN / arXiv, avec classification automatique optionnelle dans une collection. |
add_note |
write | Écrire une note Markdown dans un élément sous forme de note enfant Zotero, avec annulation possible. |
batch_modify |
write | Ajouter ou retirer en masse des collections ou des balises sur jusqu'à 200 éléments. |
Les outils d'écriture ne sont pas enregistrés du tout tant que vous n'avez pas défini enableWrites: true. Même dans ce cas, un appel non confirmé renvoie un aperçu et ne consomme aucun quota, les écritures confirmées sont limitées en débit (30/hour par défaut) et tout batch_modify portant sur plus de 20 éléments revient avec requiresConfirmation. Un agent peut lire votre bibliothèque toute la journée ; il ne peut pas la réécrire en silence.
Performances : 10,000 PDF, 42 GB, indexés en ~7 minutes
Le cœur de ce serveur MCP est le même moteur d'indexation et de recherche que celui qui se trouve derrière le benchmark de recherche de PapersGPT. Chiffres issus d'une installation Zotero réelle :
| Taille de la bibliothèque | Données brutes | Construction de l'index | Temps de requête moyen | Mémoire (RSS) | Taille de l'index |
|---|---|---|---|---|---|
| 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 |
Sur une configuration volontairement modeste — 4 cœurs / 8 GB de RAM — l'indexation de 1,506 PDF (4.5 GB) a pris 141 secondes pendant que le processus occupait 227 MB de mémoire, avec une récupération moyenne de ~15 ms. Le schéma qui compte :
- L'indexation évolue de façon à peu près linéaire. Dix fois plus de PDF, dix fois plus de temps de construction — et vous ne le payez qu'une fois par nouveau document, pas à chaque question.
- La récupération reste stable. 13 ms pour 1,000 articles, 19.5 ms pour 10,000. Ajouter des articles ne ralentit pas votre agent.
- La mémoire reste modeste. Le déchargement automatique permet de garder une bibliothèque de 42 GB interrogeable dans environ 2 GB de RAM.
- Tout est hors ligne. Aucun appel au cloud pour l'indexation ou la récupération : cela fonctionne dans un avion, sur un réseau de laboratoire verrouillé ou sous embargo.
Pourquoi « pas besoin de démarrer Zotero » change le flux de travail
Les serveurs MCP Zotero classiques sont de fines enveloppes autour de l'API locale de Zotero (http://localhost:23119/api) : pas de processus Zotero, pas de réponses. Cette unique dépendance façonne tout — vous ne pouvez pas interroger votre bibliothèque depuis un conteneur, une machine de développement distante, un script sans interface ou une session SSH ; vous ne pouvez pas chercher pendant que Zotero est en pleine synchronisation ; et chaque appel est un aller-retour de requête plutôt qu'une consultation d'index.
Comme le cœur DocsAgent lit la base de données directement, la moitié « lecture » du flux de travail est découplée de l'application Zotero :
| Serveurs MCP Zotero basés sur l'API | Zotero MCP Server 4.0 | |
|---|---|---|
| Zotero doit tourner pour chercher | Oui | Non |
| Moteur de recherche | Appels à l'API locale de Zotero | Index natif C++ BM25 + passages |
| Latence de requête sur 10,000 PDF | De plusieurs centaines de ms à plusieurs secondes | ~20 ms |
| Environnements d'exécution | Généralement un seul | JavaScript + Python |
| Transport distant / HTTP | Rare | Streamable HTTP avec authentification + RBAC |
| Sécurité des écritures | Généralement manuelle | Verrou à 3 couches + limitation de débit |
Une réserve honnête : les écritures passent toujours par l'API locale de Zotero, afin que Zotero reste la source de vérité de votre bibliothèque. Si vous voulez que l'agent importe des PDF, ajoute des notes ou réétiquette des éléments, Zotero doit être en cours d'exécution pour cette étape précise. L'indexation, la recherche et la lecture, jamais.
Cas d'usage : ce que les chercheurs en font vraiment
- Recherche dans l'éditeur avec Claude Code ou Cursor. Rédigez votre article et laissez l'agent extraire passages, résumés et BibTeX directement de votre propre bibliothèque pendant que vous tapez — sans copier-coller ni onglets de navigateur.
- Tri de littérature en terminal avec Codex ou Gemini CLI. « Trouve tous les articles de ma bibliothèque qui rapportent un rendement de conversion de puissance supérieur à 20% et ajoute-les à la collection Perovskite » —
searchsuivi debatch_modify. - Lecture hors ligne. Dans un avion ou sur le terrain, l'index répond aux requêtes localement ; rien n'a besoin du réseau.
- Bibliothèques de groupe. Pointez
zoteroGroupsvers les bibliothèques partagées de votre laboratoire et interrogez-les aux côtés de votre collection personnelle. - Compétences d'agent. Le projet publie aussi un
SKILL.mdportable, afin que les agents qui prennent en charge les compétences puissent apprendre le flux « chercher puis citer » au lieu de deviner les arguments des outils.
Confidentialité et sécurité
Vos PDF ne quittent jamais votre machine : l'indexation et la récupération sont 100% locales, et aucun document n'est envoyé à un service cloud. Quand vous activez délibérément les écritures, elles sont verrouillées, prévisualisables, limitées en débit et réversibles. Quand vous exposez délibérément le serveur en HTTP, vous obtenez des vérifications d'origine, une authentification par token et un RBAC par requête plutôt qu'un port ouvert.
Questions fréquemment posées
Dois-je garder Zotero ouvert pour que le serveur MCP fonctionne ?
Non — pour la recherche et la lecture. Le cœur lit directement votre répertoire de données Zotero (zotero.sqlite et storage/), si bien que l'indexation et la recherche fonctionnent avec Zotero fermé, et même sur une machine où l'application Zotero n'est pas lancée. Seuls les trois outils d'écriture (import d'éléments, ajout de notes, modifications en masse de balises/collections) passent par l'API locale de Zotero, qui doit donc être ouverte pour ceux-là.
Le serveur MCP Zotero prend-il en charge Python en plus de JavaScript ?
Oui. Il existe deux shells aux fonctionnalités équivalentes : @docsagent/mcp-zotero sur npm pour les utilisateurs de JavaScript/Node et docsagent-mcp-zotero sur PyPI pour Python 3.10+. Les deux exposent les mêmes 8 outils avec les mêmes schémas, codes d'erreur et verrou d'écriture, et les deux pilotent le même cœur C++ embarqué.
Quelle taille de bibliothèque Zotero peut-il gérer ?
Les bibliothèques de plusieurs milliers de PDF sont la routine : 1,000 PDF (4.2 GB) s'indexent en environ 52 secondes et se consultent en ~13 ms ; 10,000 PDF (42 GB) s'indexent en environ 7 minutes et se consultent en ~19.5 ms. Le temps de construction de l'index croît à peu près linéairement avec la taille de la bibliothèque, tandis que la latence des requêtes reste essentiellement constante.
Ma bibliothèque Zotero est-elle envoyée quelque part ?
Non. Le cœur construit et sert son index entièrement sur votre machine, et la recherche ne nécessite aucun accès réseau. Rien de vos articles n'est envoyé à PapersGPT ni à un tiers.
L'agent IA peut-il modifier ma bibliothèque Zotero ?
Uniquement si vous l'autorisez. Les outils d'écriture ne sont pas enregistrés tant que enableWrites n'est pas défini sur true ; les appels non confirmés renvoient un aperçu ; les écritures confirmées sont limitées en débit (30/hour par défaut) ; et les lots de plus de 20 éléments exigent une confirmation explicite.
Quels clients IA sont pris en charge ?
N'importe quel client MCP. Le projet documente Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI et Qwen Code, et fournit un transport Streamable HTTP pour les clients qui se connectent à distance plutôt que via stdio.
En quoi est-ce différent de l'ancienne configuration MCP de PapersGPT ?
L'ancienne configuration était un pont à usage unique construit autour de l'API locale de Zotero. La version 4.0 l'a remplacée par un cœur de recherche C++ résident, a ajouté un shell Python de première classe, a rendu la recherche fonctionnelle sans Zotero en cours d'exécution et a relevé le plafond réaliste de « quelques centaines d'articles » à 10,000+ PDF. L'ancien article est toujours en ligne comme référence historique.
Pour commencer
npx @docsagent/mcp-zotero start
Cette seule commande transforme votre bibliothèque Zotero en une base de connaissances privée et ultra-rapide pour l'agent IA que vous utilisez déjà. Les notes d'installation, les schémas d'outils et la référence de configuration complète se trouvent dans le dépôt docsagent, et il y a plus de contexte sur la page du serveur MCP.
Vous voulez le même moteur à l'intérieur de Zotero — chat intégré, lecture par lots AutoPilot, LLM locaux ? Voir la comparaison des plugins IA pour Zotero et PapersGPT. Les utilisateurs adeptes du terminal devraient aussi lire le guide de la CLI Zotero.