Zotero MCP Server: sin necesidad de abrir Zotero, búsqueda en 10,000 PDF en ~20 ms

Q: ¿El servidor Zotero MCP admite Python además de JavaScript?

Sí. Hay dos shells con las mismas funciones: @docsagent/mcp-zotero en npm para usuarios de JavaScript/Node y docsagent-mcp-zotero en PyPI para Python 3.10+. Ambos exponen las mismas 8 herramientas con los mismos esquemas, códigos de error y compuerta de escritura, y ambos gestionan el mismo núcleo C++ incluido.

Si probó un servidor Zotero MCP de primera generación, recuerda el ritual: Zotero tenía que estar abierto, la API local tenía que estar habilitada y cada consulta recorría su biblioteca registro a registro de metadatos. Eso está bien para una demo. No está bien cuando su biblioteca contiene 5,000 PDF y un agente lanza veinte búsquedas antes de que usted termine de escribir una frase.

El nuevo Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, publicado el 21 de septiembre de 2026 — es una máquina distinta. Incluye dos shells (JavaScript y Python) sobre un núcleo de búsqueda C++ nativo residente que lee directamente el directorio de datos de Zotero. La búsqueda funciona sin abrir Zotero, y las bibliotecas de 10,000+ PDF se convierten en una base de conocimiento a nivel de milisegundos para Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline o cualquier otro cliente MCP.

Esta es la guía de la nueva versión: qué cambió, cómo instalarla en ambos runtimes, las 8 herramientas que recibe su agente y las cifras de benchmark para bibliotecas realmente grandes.

Novedades de Zotero MCP Server 4.0

Dos shells, un núcleo. El mismo contrato de herramientas está disponible como paquete TypeScript en npm (@docsagent/mcp-zotero) y como paquete Python en PyPI (docsagent-mcp-zotero). Elija el runtime que ya usa su stack: las herramientas, los esquemas, los códigos de error y la compuerta de escritura son idénticos.
No hace falta iniciar Zotero. El núcleo en C++ lee ~/Zotero/zotero.sqlite y el directorio storage/ directamente, así que la indexación y la búsqueda siguen funcionando con Zotero cerrado — o aunque nunca se haya instalado en esa máquina.
Un servicio residente, no un subproceso por llamada. El núcleo se ejecuta en segundo plano en http://127.0.0.1:23120/rpc, reconstruye su índice a medida que cambia su biblioteca y se mantiene caliente entre reinicios del cliente MCP. Su agente nunca paga el costo del arranque en frío.
Diseñado para bibliotecas grandes. Búsqueda de texto completo BM25 con índice invertido + ranking de pasajes sobre 1,000+ PDF en ~15 ms, con un consumo de memoria de unos pocos cientos de MB en lugar de gigabytes.
8 herramientas MCP (5 de lectura + 3 de escritura) con argumentos validados por esquema JSON, presupuestos de tokens, deduplicación de resultados y una compuerta de seguridad de escritura de tres capas.
Dos transportes. stdio para clientes MCP locales; Streamable HTTP (/mcp) con comprobaciones de origen, autenticación por API key u OAuth 2.0 (RFC 7662) y RBAC por solicitud cuando lo despliega de forma remota.
Un solo archivo de configuración. ~/.docsagent/config.json lo comparten la shell de JS, la shell de Python y el núcleo en C++.

Cómo funciona: dos shells sobre un núcleo 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 separación importa. La shell es delgada: contiene los esquemas de las herramientas, valida los argumentos, aplica los presupuestos de tokens y nunca toca sus archivos de Zotero. El núcleo hace el trabajo pesado en C++, y por eso el mismo motor sirve tanto al paquete de npm como al de PyPI con un comportamiento byte a byte idéntico.

Inicio rápido: conecte Zotero a su agente de IA en 3 pasos

Opción A — JavaScript / npm

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

Luego agregue el servidor a la configuración de su cliente MCP (Claude Desktop, Cursor, Cline, Qwen Code, …):

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

Opción 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

Luego registre la shell de Python de la misma manera:

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

Reinicie su cliente MCP y pregúntele algo como "¿Qué dice mi biblioteca Zotero sobre la degradación de baterías en celdas de sodio-ion?" — el agente llama a search, obtiene pasajes clasificados por BM25 con citas zotero:KEY y responde a partir de sus PDF en lugar de la web abierta.

Ambas CLI también exponen comandos de ciclo de vida del núcleo — start, stop, restart, status (Python los ejecuta bajo un subcomando core, es decir, docsagent-mcp-zotero core restart) — además de --transport streamable-http cuando quiere servir /mcp por la red.

Las 8 herramientas que puede llamar su agente

Herramienta	Tipo	Qué hace
`list_sources`	lectura	Todas las fuentes consultables, con sus capacidades y recuentos de documentos. Llame a esta primero.
`search`	lectura	Búsqueda transversal en la biblioteca sobre ítems, anotaciones o notas; profundidad `ids` / `snippets` / `full`, filtros por etiquetas, rango de años, tipo de ítem, autores y colecciones.
`get_content`	lectura	Lee una entrada como pasajes clasificados por consulta (`k`) o texto completo con paginación por desplazamiento.
`get_metadata`	lectura	Metadatos, resumen, anotaciones, notas y citas (BibTeX / CSL-JSON / con formato).
`list_library`	lectura	Navegue por colecciones, ítems, etiquetas, búsquedas guardadas y notas independientes.
`import_item`	escritura	Importe PDF locales o resuelva DOI / ISBN / arXiv IDs, con clasificación automática opcional en colecciones.
`add_note`	escritura	Escriba una nota en Markdown de vuelta a un ítem como nota secundaria de Zotero, con reversión.
`batch_modify`	escritura	Agregue o quite colecciones o etiquetas en bloque en hasta 200 ítems.

Las herramientas de escritura no se registran en absoluto a menos que establezca enableWrites: true. Incluso entonces, una llamada sin confirmar devuelve una vista previa y no consume cuota, las escrituras confirmadas tienen límite de velocidad (30/hour por defecto) y cualquier batch_modify de más de 20 ítems vuelve con requiresConfirmation. Un agente puede leer su biblioteca todo el día; no puede reescribirla en silencio.

Rendimiento: 10,000 PDF, 42 GB, indexados en ~7 minutos

El núcleo de este servidor MCP es el mismo motor de indexación y recuperación que está detrás del benchmark de búsqueda de PapersGPT. Cifras de una instalación real de Zotero:

Tamaño de la biblioteca	Datos brutos	Construcción del índice	Tiempo medio de consulta	Memoria (RSS)	Tamaño del índice
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

En una configuración deliberadamente modesta — 4 núcleos / 8 GB de RAM — la indexación de 1,506 PDF (4.5 GB) tomó 141 segundos mientras el proceso ocupaba 227 MB de memoria, con una recuperación promedio de ~15 ms. El patrón que importa:

La indexación escala de forma aproximadamente lineal. Diez veces más PDF, diez veces el tiempo de construcción, y lo paga una vez por documento nuevo, no por pregunta.
La recuperación se mantiene plana. 13 ms con 1,000 artículos, 19.5 ms con 10,000. Agregar artículos no hace más lento a su agente.
La memoria se mantiene modesta. La descarga automática mantiene una biblioteca de 42 GB consultable dentro de unos 2 GB de RAM.
Todo es offline. Ninguna llamada a la nube para indexar o recuperar, así que funciona en un avión, en una red de laboratorio restringida o bajo embargo.

Por qué "no hace falta iniciar Zotero" cambia el flujo de trabajo

Los servidores Zotero MCP clásicos son envoltorios delgados alrededor de la API local de Zotero (http://localhost:23119/api): sin proceso de Zotero, sin respuestas. Esa única dependencia lo condiciona todo: no puede buscar en su biblioteca desde un contenedor, una máquina de desarrollo remota, un script headless o una sesión SSH; no puede buscar mientras Zotero está sincronizando; y cada llamada es un ida y vuelta de solicitud en lugar de una consulta al índice.

Como el núcleo de DocsAgent lee la base de datos directamente, la mitad de lectura del flujo de trabajo queda desacoplada de la aplicación Zotero:

	Servidores Zotero MCP basados en API	Zotero MCP Server 4.0
Zotero debe estar en ejecución para buscar	Sí	No
Backend de búsqueda	Llamadas a la API local de Zotero	Índice nativo C++ BM25 + pasajes
Latencia de consulta con 10,000 PDF	De cientos de ms a segundos	~20 ms
Runtimes	Normalmente uno	JavaScript + Python
Transporte remoto / HTTP	Poco frecuente	Streamable HTTP con autenticación + RBAC
Seguridad de escritura	Normalmente manual	Compuerta de 3 capas + límite de velocidad

Una advertencia honesta: las escrituras siguen pasando por la propia API local de Zotero, para que Zotero siga siendo la fuente de verdad de su biblioteca. Si quiere que el agente importe PDF, agregue notas o reetiquete ítems, Zotero debe estar en ejecución para ese paso concreto. La indexación, la búsqueda y la lectura nunca lo requieren.

Casos de uso: qué hacen realmente los investigadores con esto

Investigación dentro del editor con Claude Code o Cursor. Escriba su artículo y deje que el agente extraiga pasajes, resúmenes y BibTeX directamente de su propia biblioteca mientras escribe: sin copiar y pegar, sin pestañas del navegador.
Triaje de literatura desde el terminal con Codex o Gemini CLI. "Encuentra todos los artículos de mi biblioteca que reporten una eficiencia de conversión de potencia superior al 20% y agrégalos a la colección Perovskite" — search seguido de batch_modify.
Lectura sin conexión. En un avión o en el campo, el índice responde las consultas localmente; nada necesita red.
Bibliotecas de grupo. Apunte zoteroGroups a las bibliotecas compartidas de su laboratorio y búsquelas junto con su colección personal.
Skills para agentes. El proyecto también publica un SKILL.md portátil, así que los agentes que admiten skills pueden aprender el flujo de buscar y citar en lugar de adivinar los argumentos de las herramientas.

Privacidad y seguridad

Sus PDF nunca salen de su máquina: la indexación y la recuperación son 100 % locales y no se envía ningún documento a ningún servicio en la nube. Cuando habilita las escrituras de forma deliberada, están controladas por compuertas, se pueden previsualizar, tienen límite de velocidad y son reversibles. Cuando expone deliberadamente el servidor por HTTP, obtiene comprobaciones de origen, autenticación por token y RBAC por solicitud en lugar de un puerto abierto.

Preguntas frecuentes

¿Necesito mantener Zotero en ejecución para que funcione el servidor MCP?

No, para buscar y leer. El núcleo lee directamente su directorio de datos de Zotero (zotero.sqlite y storage/), así que la indexación y la búsqueda funcionan con Zotero cerrado, e incluso en una máquina donde la aplicación de escritorio de Zotero no está en ejecución. Solo las tres herramientas de escritura (importar ítems, agregar notas y ediciones masivas de etiquetas o colecciones) pasan por la API local de Zotero, por lo que Zotero debe estar abierto para esas.

¿El servidor Zotero MCP admite Python además de JavaScript?

Sí. Hay dos shells con las mismas funciones: @docsagent/mcp-zotero en npm para usuarios de JavaScript/Node y docsagent-mcp-zotero en PyPI para Python 3.10+. Ambos exponen las mismas 8 herramientas con los mismos esquemas, códigos de error y compuerta de escritura, y ambos gestionan el mismo núcleo C++ incluido.

¿Qué tamaño de biblioteca Zotero puede manejar?

Las bibliotecas de miles de PDF son habituales: 1,000 PDF (4.2 GB) se indexan en unos 52 segundos y se consultan en ~13 ms; 10,000 PDF (42 GB) se indexan en unos 7 minutos y se consultan en ~19.5 ms. El tiempo de construcción del índice crece de forma aproximadamente lineal con el tamaño de la biblioteca, mientras que la latencia de consulta se mantiene prácticamente constante.

¿Se sube mi biblioteca Zotero a algún sitio?

No. El núcleo construye y sirve su índice por completo en su máquina, y la búsqueda no requiere acceso a la red. No se envía nada sobre sus artículos a PapersGPT ni a ningún tercero.

¿Puede el agente de IA modificar mi biblioteca Zotero?

Solo si usted se lo permite. Las herramientas de escritura no se registran a menos que enableWrites esté en true; las llamadas sin confirmar devuelven una vista previa; las escrituras confirmadas tienen límite de velocidad (30/hour por defecto); y los lotes de varios ítems de más de 20 ítems requieren confirmación explícita.

¿Qué clientes de IA son compatibles?

Cualquier cliente MCP. El proyecto documenta Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI y Qwen Code, y ofrece un transporte Streamable HTTP para los clientes que se conectan de forma remota en lugar de por stdio.

¿En qué se diferencia de la configuración MCP anterior de PapersGPT?

La configuración anterior era un puente de un solo propósito construido alrededor de la API local de Zotero. La versión 4.0 la reemplazó por un núcleo de búsqueda C++ residente, añadió una shell de Python de primera clase, hizo que la búsqueda funcione sin Zotero en ejecución y elevó el techo realista de "unos cientos de artículos" a 10,000+ PDF. El artículo antiguo sigue en línea como referencia histórica.

Primeros pasos

npx @docsagent/mcp-zotero start

Ese único comando convierte su biblioteca Zotero en una base de conocimiento privada y ultrarrápida para el agente de IA que ya use. Las notas de configuración, los esquemas de las herramientas y la referencia completa de configuración están en el repositorio docsagent, y hay más contexto en la página del servidor MCP.

¿Quiere el mismo motor dentro del propio Zotero — chat integrado, lectura por lotes con AutoPilot, LLM locales? Vea la comparativa de plugins de IA para Zotero y PapersGPT. Quienes prefieren el terminal también deberían leer la guía de Zotero CLI.