Zoteus

_{Una sesión real, 6 de septiembre de 2026, contra la biblioteca propia del mantenedor. Las llamadas a herramientas se muestran como una secuencia acelerada. La grabación completa está en zoteus.com.}

Instalación

Para la mayoría de los clientes no hay nada que descargar: el cliente obtiene Zoteus con npx la primera vez que se ejecuta. ¿Nuevo en servidores MCP? Empieza con docs/getting-started.md.

Cliente	Cómo
Claude Desktop	Descarga el paquete para tu sistema desde la última versión, zoteus-macos.mcpb, zoteus-windows.mcpb o zoteus-linux.mcpb, y haz doble clic en él. Esta es la instalación con una pantalla de ajustes (Settings → Extensions → Zoteus) y permisos por herramienta.
Claude Code	claude mcp add --transport stdio zoteus -- npx -y @oscardvs/zoteus
Claude Code, como plugin	/plugin marketplace add oscardvs/zoteus, luego /plugin install zoteus@zoteus. El mismo servidor, más cuatro habilidades de investigación que enseñan a Claude a citar pasajes con páginas, construir tablas de evidencia, citar y ordenar la biblioteca. Establece la clave API opcional con /plugin → Zoteus → Configure options. Claude Desktop no muestra ajustes para un plugin, así que usa .mcpb allí. Ver plugins/zoteus.
Cursor, VS Code, Zed, Codex, Gemini CLI, cualquier cliente MCP	npx add-mcp @oscardvs/zoteus, o añade npx -y @oscardvs/zoteus como servidor stdio manualmente.
claude.ai en el navegador	Añade un conector personalizado que apunte a un Zoteus alojado o a tu propia instancia remota.
ChatGPT (web)	Necesita el modo Developer en un plan de ChatGPT de pago (Settings → Security and login). Luego Plugins → Create app, con la URL del servidor de un Zoteus alojado (https://mcp.zoteus.com/mcp) o de tu propia instancia remota, y OAuth como autenticación. ChatGPT solo se conecta a servidores remotos, así que la instalación npx no aplica.

Luego ejecuta la aplicación de escritorio de Zotero. Las lecturas, y las escrituras en la biblioteca personal que pasan por la aplicación (añadir elementos por identificador, adjuntos, anotaciones, papelera y restaurar), no necesitan clave en la nube. Añade una clave API de Zotero para sincronización, bibliotecas de grupo, ediciones de metadatos, etiquetas y colecciones, y para cuando la aplicación esté cerrada:

claude mcp add --transport stdio zoteus -e ZOTERO_API_KEY=xxxxx -- npx -y @oscardvs/zoteus

Obtén una clave en zotero.org/settings/keys. En la aplicación de escritorio, activa Settings → Advanced → "Allow other applications on this computer to communicate with Zotero". Paso a paso para cada cliente, con capturas de pantalla: zoteus.com/docs/connect-claude-to-zotero.

Actualizar una instalación de extensión de escritorio. Un .mcpb instalado manualmente (o un .dxt más antiguo) no se actualiza automáticamente. Activa Check for updates en los ajustes de la extensión (o establece ZOTEUS_UPDATE_CHECK=true) y Zoteus consulta GitHub una vez al día, luego lo indica en el chat mediante zotero_whoami cuando existe una versión más reciente; descarga el nuevo paquete para tu sistema y reinstálalo. La comprobación está desactivada por defecto. Las instalaciones npx siempre ejecutan la última versión publicada.

Qué hace

Zoteus expone herramientas de investigación, con espacio de nombres zotero_*, que buscan en la biblioteca por palabra clave o por significado, devuelven pasajes de tus PDFs con localizadores de página, muestran páginas de PDF y figuras como imágenes, formatean bibliografías con citeproc-js en cualquier estilo CSL, añaden elementos por DOI o id de arXiv, y crean, editan, etiquetan y organizan elementos con escrituras versionadas y una papelera reversible. Cuando la aplicación de escritorio de Zotero está en ejecución, las lecturas y las escrituras en la biblioteca personal van directamente a ella y no necesitan clave API en la nube; la Zotero Web API v3 es el respaldo para sincronización, bibliotecas de grupo y cuando la aplicación está cerrada. Zoteus está escrito en TypeScript, se ejecuta en tu máquina y tiene licencia MIT.

Características

• Busca en tu propia biblioteca. Búsqueda híbrida por palabra clave y semántica sobre títulos, resúmenes, creadores y etiquetas, más búsqueda de texto completo dentro de tus PDFs y notas, con el pasaje coincidente devuelto junto con su número de página. Tus propias notas y anotaciones de PDF se indexan bajo el elemento al que pertenecen, así que "¿dónde me opuse a esto?" es una pregunta que la búsqueda puede responder. Establece ZOTEUS_INDEX_FULLTEXT (o pasa fulltext:true a zotero_index) y la búsqueda indexada también cubre el texto del cuerpo de los PDFs disponibles dentro de los límites configurados, de modo que una afirmación que nunca llegó a un resumen sigue siendo localizable.
• Formatea citas. Zoteus lee los datos de citas en tu biblioteca de Zotero y los formatea con citeproc-js en cualquier estilo CSL del repositorio de estilos CSL.
• Añade un artículo por identificador. Pasa un DOI o id de arXiv y Zoteus obtiene los metadatos y archiva el elemento. Esto funciona de serie con resolutores integrados; un servidor de traducción de Zotero lo extiende a ISBN, PMID y URLs (ver docs/resolver.md).
• Escribe de vuelta. Crea elementos, edita, etiqueta y organiza. Las escrituras están versionadas con reintentos de bloqueo optimista, la papelera es reversible por defecto y la eliminación permanente es opcional y requiere confirmación.
• Escribe directamente en la aplicación de escritorio. Añadir elementos por identificador, adjuntos, anotaciones, y papelera y restaurar van a tu Zotero en ejecución sin clave API en la nube. En Zotero 10+ esto usa la API local detrás de una clave que concedes una vez ("Always Allow"); en Zotero 9 y anteriores, cuya API local es de solo lectura, usa el protocolo de conector que usan las extensiones del navegador. La Web API en la nube es el respaldo para bibliotecas de grupo, ediciones de metadatos, etiquetas, colecciones y búsquedas guardadas, y para cuando la aplicación no está en ejecución.
• Anota PDFs y adjunta archivos. zotero_annotate añade resaltados, subrayados y notas, los mismos objetos que crea el lector de PDF de Zotero. Cita el pasaje y Zoteus lo localiza en el PDF y ancla la anotación a las líneas que ocupa, incluyendo saltos de línea y guiones, así que no se necesitan coordenadas de página. zotero_attach_file almacena un archivo local o una URL como adjunto bajo cualquier elemento.
• Fundamenta afirmaciones en el PDF. zotero_get_fulltext devuelve el pasaje relevante con desplazamientos de caracteres, el encabezado más cercano y un localizador de página. Cuando Zotero no ha indexado el PDF o EPUB, extrae el texto sobre la marcha, desde la aplicación de escritorio en ejecución o desde la propia carpeta de almacenamiento de Zotero, así que un archivo añadido hace un minuto es legible de inmediato. También devuelve la tabla de contenidos de un PDF (outline:true) y cualquier rango de páginas bajo demanda, así que trabajar con un libro de 400 páginas cuesta unas pocas llamadas pequeñas en lugar de una que devuelva todo el libro.
• Mira la página. zotero_pdf_images renderiza cualquier página de un PDF a una imagen que el modelo puede ver, así que una figura, una tabla, una ecuación o una página escaneada sin capa de texto ya no están fuera de alcance, y extrae las figuras incrustadas en una página a archivos, como pdfimages, cada una con su posición en la página. Dibuja a través del mismo pdfjs que lee el texto, así que no necesita nada que no esté ya instalado.
• Sigue la literatura. zotero_scholar busca las referencias de un artículo, obras que lo citan y obras relacionadas a través de OpenAlex, con Crossref como respaldo, y puede marcar cuáles de ellas ya están en tu biblioteca.
• Importa una bibliografía, encuentra duplicados, fúndelos. zotero_import lee BibTeX, RIS y CSL-JSON como texto o archivo sin un servidor de traducción, recupera un DOI o id de arXiv de las primeras páginas de un PDF, y puede comprobar la biblioteca en busca de una copia existente antes de guardar. zotero_merge_items fusiona duplicados en un solo registro: previsualiza por defecto, rellena solo lo que le falta al maestro, une etiquetas, colecciones y relaciones, reasigna notas y adjuntos, y envía las copias vaciadas a la papelera (ver docs/importing-bibliographies.md, docs/duplicates-and-merging.md).
• Copias de acceso abierto y avisos de retractación. zotero_scholar informa de un PDF de acceso abierto cuando OpenAlex conoce uno y zotero_attach_file puede obtenerlo y adjuntarlo desde el DOI, registrando qué versión es; zotero_scholar también informa de registros de retractación y corrección de Crossref y OpenAlex, como registros en lugar de un veredicto (docs/open-access-pdfs.md, docs/retraction-notices.md).
• Tablas de evidencia y documentos de Word. Un prompt zotero-evidence-table más zotero_evidence_table renderizan pasajes recopilados como una tabla Markdown o CSV cuyas citas no pueden desviarse del pasaje que citan, y zotero_word_document escribe un .docx cuyas citas son códigos de campo vivos de Zotero (docs/evidence-tables.md, docs/word-documents.md; actualizar los campos en Word aún no está verificado).
• Escaneos, varias bibliotecas, incrustaciones locales. zotero_get_fulltext lee un PDF sin capa de texto a través de un motor OCR opcional (docs/ocr.md); un directorio de datos contiene un índice de búsqueda por biblioteca y zotero_semantic_search puede buscar en varias a la vez (docs/multiple-library-indexes.md); y ZOTEUS_EMBEDDINGS=ollama incrusta a través de un daemon local de Ollama sin clave API (docs/ollama.md). zoteus index build ejecuta una construcción de índice sin interfaz desde la línea de comandos.
• Soporte para agentes. 34 herramientas con salidas estructuradas, MCP Resources y Prompts, y un árbol de herramientas generado para el patrón code-execution-with-MCP.

Cómo funciona

1. Instala con un comando npx, o el .mcpb de un clic.
2. Conecta ejecutando la aplicación de escritorio para acceso local sin clave, o pegando tu clave API de Zotero.
3. Pregunta. Tu cliente MCP ahora puede buscar, citar, añadir y organizar tu biblioteca.

Zoteus detecta una aplicación de escritorio de Zotero en ejecución y habla con ella directamente: la API local sin clave para lecturas (PDFs completos, resultados de búsquedas guardadas, la construcción del índice de búsqueda semántica), y la propia aplicación para escrituras en la biblioteca personal (importaciones, anotaciones, adjuntos, papelera). La Web API v3 en la nube es el respaldo, y sigue siendo necesaria para sincronización, bibliotecas de grupo y escrituras cuando la aplicación no está en ejecución. Detalles: docs/writing.md.

Escribir en una biblioteca de grupo. Las escrituras de grupo siempre van a la nube, incluso para un grupo que la aplicación de escritorio está manteniendo y leyendo sin clave: las rutas de escritura de la aplicación se dirigen a tu biblioteca personal y a nada más. Necesitan ZOTERO_API_KEY con acceso de lectura/escritura a ese grupo, y un grupo cuya configuración te permita editar su biblioteca. Dirígete al grupo por el library_id numérico de zotero_groups (library_type:"group" solo no es suficiente), y toma las claves de colección de ese mismo grupo. Ver Bibliotecas de grupo.

Empieza con un pasaje verificado. Elige un cliente y conexión, comprueba la disponibilidad de búsqueda, luego recupera y verifica un pasaje. No se requiere un índice completo de la biblioteca. Para PDFs solo locales, WebDAV o escaneados, ver Disponibilidad de PDF.

Configuración de búsqueda semántica. El primer zotero_semantic_search construye el índice de la biblioteca en segundo plano. En bibliotecas muy grandes también puedes ejecutar zotero_index (action:"build") tú mismo, luego consulta action:"status" hasta que termine. La construcción pagina tu biblioteca a través del mismo camino local-primero que cualquier otra lectura, así que no necesita clave API en la nube mientras la aplicación de escritorio está en ejecución. Eso cubre tu biblioteca personal y, en Zotero 10+, cualquier biblioteca de grupo que la aplicación mantenga; se necesita una clave cuando la aplicación está cerrada, y para un grupo que la aplicación no mantiene. Incrustación mediante una API en una biblioteca grande. Una compilación de texto completo de una biblioteca de 10 000 elementos implica decenas de miles de solicitudes, y con el ritmo predeterminado, la tasa se mantiene en el límite de tokens por minuto de OpenAI, sea cual sea tu nivel. Una solicitud con límite de tasa se retrasa y se reintenta en lugar de fallar la compilación, y una compilación que aún termina corta conserva todo lo que indexó: ejecuta zotero_index action:"build" de nuevo y se reanuda, incrustando solo los pasajes que aún no tienen vector (action:"refresh" es el que empieza de cero). Para ajustar el ritmo de antemano, establece ZOTEUS_EMBED_BATCH_SIZE=256 y ZOTEUS_EMBED_BATCH_DELAY_MS=8000. Consulta docs/semantic-search.md.

La clasificación por vectores es opcional. La búsqueda por palabras clave (BM25) funciona de serie en todas partes. Los vectores en el dispositivo necesitan @huggingface/transformers, que el paquete de extensión de escritorio no puede incluir (el árbol de dependencias resuelto, incluidos los binarios nativos de onnxruntime, pesa unos 700 MB): instálalo en un directorio propio (mkdir -p ~/.zoteus-deps && cd ~/.zoteus-deps && npm init -y && npm i @huggingface/transformers) y establece ZOTEUS_TRANSFORMERS_PATH a ~/.zoteus-deps/node_modules. No npm i -g: Claude Desktop ejecuta el servidor en su propio Node integrado, por lo que una instalación global bajo un gestor de versiones se sitúa junto a un Node que la extensión nunca ejecuta. Cuando los vectores no están disponibles, Zoteus lo indica en el estado de zotero_index, zotero_whoami y zotero_semantic_search en lugar de devolver silenciosamente nada. Consulta docs/semantic-search.md.

Configuración

Variable	Predeterminado	Propósito
ZOTERO_API_KEY	ninguno	Autenticación en la nube (sincronización, grupos, escrituras sin la aplicación de escritorio; opcional en otros casos)
ZOTEUS_LOCAL	auto	auto|on|off: usa la aplicación de escritorio de Zotero (lecturas + escrituras en la biblioteca personal)
ZOTEUS_LOCAL_API_KEY	ninguno	Preaprovisiona la clave de escritura de escritorio de Zotero 10+ (si no, se concede una vez, en la aplicación)
ZOTEUS_EMBEDDINGS	local	local|ollama|openai|gemini|off para la búsqueda semántica
ZOTEUS_EMBEDDING_MODEL	predeterminado del proveedor	El modelo que el proveedor usa para incrustar, incluido local: Xenova/multilingual-e5-small para una biblioteca en alemán o multilingüe, Xenova/all-MiniLM-L6-v2 por defecto
ZOTEUS_EMBEDDING_DTYPE	fp32	Precisión de pesos del modelo en el dispositivo: q8 descarga Xenova/multilingual-e5-small a 129 MB en lugar de 465 MB. Por encima de fp32 se une a la identidad del incrustador, por lo que cambiarlo requiere una recompilación
ZOTEUS_EMBED_BATCH_SIZE	32	Pasajes por llamada de incrustación. Redúcelo si un proveedor de API rechaza una solicitud completa (OpenAI responde 400 por encima de 300K tokens por solicitud)
ZOTEUS_EMBED_BATCH_DELAY_MS	0	Pausa entre llamadas de incrustación. Auméntala si un proveedor de API limita la tasa de una compilación grande: 256 y 8000 juntos mantienen una compilación de texto completo cerca de 400K tokens/min
ZOTEUS_INDEX_OWN_WORDS	true	Indexa tus propias notas secundarias y anotaciones de PDF como pasajes buscables
ZOTEUS_INDEX_FULLTEXT	false	Indexa el texto del cuerpo de los PDF para la búsqueda semántica (opt-in; costoso)
ZOTEUS_INDEX_BACKEND	auto	auto|sqlite|memory: dónde vive el índice de búsqueda. auto usa SQLite (FTS5) en Node 22.13+, que es lo que necesita una biblioteca grande
ZOTEUS_TRANSFORMERS_PATH	ninguno	Dónde encontrar @huggingface/transformers para incrustaciones de local cuando la instalación no puede verlo (extensión de escritorio)
ZOTEUS_LOG_FILE	ninguno	Añade cada línea de registro a este archivo, para un servidor que se ejecuta sin terminal
ZOTEUS_ALLOW_DELETE	false	Debe ser true o zotero_delete_items rechaza cada llamada; la herramienta permanece listada a menos que ZOTEUS_READ_ONLY=true

Tabla completa en docs/configuration.md. Para ejecutar una instancia compartida o remota, consulta docs/remote-oauth.md (autohospeda el OAuth remoto en loopback o detrás de tu propio proxy).

Documentación

zoteus.com/docs · Conecta Claude a Zotero · Conecta ChatGPT a Zotero · Bibliotecas de grupo para equipos de revisión · Zoteus y zotero-mcp, lado a lado

En este repositorio: Primeros pasos · Configuración · Importación y resolución · Importación de bibliografías · Duplicados y fusión · Arquitectura · Escrituras seguras · Modelo de amenazas · Citas · Documentos de Word · Tablas de evidencia · Búsqueda semántica · Varios índices de biblioteca · Incrustaciones de Ollama · OCR · Contexto académico · PDF de acceso abierto · Avisos de retractación · Línea de comandos · Configuración de laboratorio · Ejecución de código · Despliegue · Desinstalación

Zoteus está listado en el Registro MCP como io.github.oscardvs/zoteus, en mcpservers.org y en la visión general de proyectos MCP de Zotero de Citation Styler.

Desinstalación

Zoteus escribe todo lo que deriva (el índice de búsqueda, los pesos del modelo en el dispositivo, la caché de verificación de actualizaciones, la clave de API local concedida) en un solo directorio: ZOTEUS_DATA_DIR si lo estableces, o si no, la ruta de datos de aplicación predeterminada de tu sistema operativo. Detén el servidor, elimínalo de la configuración de tu cliente MCP y luego borra ese directorio; tu biblioteca de Zotero vive en otro lugar y nada aquí la toca. Pasos completos y rutas por plataforma: docs/uninstall.md.

Privacidad

Zoteus se ejecuta en tu máquina o en el servidor que configures. El registro de uso está desactivado por defecto. Los resultados de las herramientas van a tu cliente de IA elegido, y las funciones habilitadas contactan con Zotero y los servicios académicos, de PDF o de incrustación que requieran. Política completa: PRIVACY.md.

Contribuciones

Las contribuciones son bienvenidas; consulta CONTRIBUTING.md. Zoteus tiene licencia MIT.

Agradecimientos

Construido sobre el Protocolo de Contexto de Modelo, la API web de Zotero, citeproc-js y el Lenguaje de Estilo de Citas. No está afiliado ni respaldado por la Corporation for Digital Scholarship / Zotero.

citeproc-js implementa el Lenguaje de Estilo de Citas. (c) Frank Bennett, usado bajo la Licencia de Atribución Pública Común 1.0. https://citationstyles.org/ Los avisos de dependencias se recopilan en THIRD_PARTY_NOTICES.md.