cli-anything-zotero

Servidor CLI y MCP para Zotero 7/8 — 52 herramientas para que la IA gestione tu biblioteca de investigación localmente. Busca, importa, exporta, PDF, notas y más.

GitHub

132

Prueba este MCPPatrocinado

Documentación

cli-anything-zotero

Deja que la IA gestione tu biblioteca de Zotero.

中文文档 | English | Roadmap | TODO | Comandos

Aviso de legado MCP: v0.9.5 es la versión final con el comando zotero-mcp y el extra cli-anything-zotero[mcp]. Las nuevas versiones priorizan CLI/SDK. Los usuarios existentes de MCP deben fijar pip install "cli-anything-zotero[mcp]==0.9.5" o usar la rama legacy/mcp.

Para no programadores

Esta herramienta está diseñada para ser usada por la IA, no memorizada por ti. Después de una instalación sencilla (~3 minutos), solo habla con tu asistente de IA en lenguaje natural:

"Encuentra artículos sobre diabetes y enfermedad renal en mi biblioteca de Zotero"

"Importa este DOI a mi colección CKM: 10.1038/s41586-024-07871-6"

"Exporta todos los artículos de mi colección de tesis como BibTeX"

"Encuentra PDFs para los elementos de mi colección de revisión que les falten"

Todo lo que necesitas hacer:

Sigue los pasos de Instalación a continuación
Dile a tu asistente de IA (Claude Code, Cursor, etc.) lo que necesitas
Eso es todo

Qué hace

Construido sobre CLI-Anything por HKUDS, esta herramienta da a los agentes de IA acceso completo a tu biblioteca local de Zotero a través de un JS Bridge — un plugin ligero de Zotero que expone un endpoint JavaScript privilegiado.

Requisito previo: la aplicación de escritorio de Zotero debe estar ejecutándose. Esto es intencional — automatizamos el cliente local (Connector, Local API, CLI Bridge), no un sustituto de API solo en la nube.

Capacidades clave:

Buscar y navegar — búsqueda por palabras clave, búsqueda de texto completo en PDFs, árbol de colecciones, etiquetas
Importar — desde DOI, PMID, archivos RIS/BibTeX, o JSON
Exportar — BibTeX, CSL-JSON, RIS, CSV, citas formateadas
Gestión de PDFs — adjuntar archivos, encontrar PDFs automáticamente en línea, buscar anotaciones
Operaciones de escritura — actualizar metadatos, gestionar etiquetas, añadir notas, activar sincronización
Citas DOCX — convertir marcadores {{zotero:ITEMKEY}} en texto estático o campos Zotero actualizables (ver más abajo)
Avanzado — ejecutar JS arbitrario de Zotero, búsqueda semántica con embeddings locales, análisis de IA

Todas las operaciones de escritura se ejecutan localmente a través del JS Bridge — no se requiere clave API ni conexión a internet.

Citas DOCX: estáticas vs dinámicas

Los borradores escritos por IA deben usar marcadores como {{zotero:ITEMKEY}} o {{zotero:KEY1,KEY2}}, y luego convertirlos con los comandos docx.

Modo	Comando	Salida	Software adicional
Estático (predeterminado para finales simples)	`docx render-citations` o `docx cite --mode static`	Citas en texto plano + bibliografía estática	No. Solo `pip install` + JS Bridge + Zotero ejecutándose (Local API).
Dinámico (campos actualizables)	`docx insert-citations` o `docx cite --mode dynamic`	Campos reales de Zotero en Word/LibreOffice + bibliografía actualizable	Sí — se requiere stack adicional (ver tabla abajo).
Automático	`docx cite --mode auto`	Elige dinámico si el stack está listo, si no estático	Igual que dinámico cuando esté disponible

El modo dinámico es opcional y no se instala solo con pip. También necesitas:

Requisito	Por qué
Zotero Desktop (ejecutándose)	Biblioteca fuente + integración con procesador de textos
Plugin CLI Bridge (`zotero-cli app install-plugin`)	Puente local privilegiado usado para la conversión
LibreOffice	Abre/guarda el DOCX durante la inserción de campos
Plugin Zotero para LibreOffice	Crea campos de cita/bibliografía actualizables

Verifica la máquina antes de confiar en el modo dinámico:

zotero-cli --json docx doctor

Si doctor informa que falta LibreOffice / el add-in de LO / Bridge, usa el modo estático (o instala las piezas faltantes). En macOS la ruta dinámica completa está probada de extremo a extremo; en Windows/Linux, doctor funciona pero abrir/guardar automáticamente puede requerir interacción manual con LibreOffice hasta que se verifique.

Una sola vez cuando no estés seguro:

zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

Uso CLI primero

cli-anything-zotero ahora se mantiene como una herramienta que prioriza CLI/SDK. La interfaz principal es el comando de shell zotero-cli, que funciona bien con Codex, Claude Code, Cursor, scripts de shell y otros agentes que pueden ejecutar comandos de terminal.

Para usuarios MCP heredados, instala la versión MCP congelada explícitamente:

pip install "cli-anything-zotero[mcp]==0.9.5"

La rama legacy/mcp y la versión v0.9.5 siguen disponibles, pero MCP no recibe mantenimiento de nuevas funciones después de esa línea.

Instalación

Requisitos previos: Python 3.10+, Zotero 7/8/9 (ejecutándose).

Paso 1: Instala el paquete

pip install cli-anything-zotero

Esto instala el comando zotero-cli. El antiguo comando cli-anything-zotero sigue disponible como alias de compatibilidad.

Paso 2: Instala el Plugin JS Bridge (una sola vez, ambos modos)

zotero-cli app install-plugin

La primera instalación requiere pasos manuales en Zotero:

El comando genera un archivo .xpi e imprime su ruta
En Zotero: Herramientas → Plugins → icono de engranaje → Instalar Plugin Desde Archivo...
Selecciona el archivo .xpi, luego reinicia Zotero

Después de la primera instalación, las actualizaciones futuras vía app install-plugin son automáticas.

Para usuarios existentes que actualizan al flujo de citas DOCX dinámicas, actualiza tanto el paquete de Python como el plugin bridge de Zotero:

python -m pip install -U cli-anything-zotero
zotero-cli app install-plugin
# restart Zotero
zotero-cli app plugin-status
zotero-cli docx doctor

Paso 3: Configura tu cliente de IA

No se requiere configuración específica del cliente. Dile a tu asistente de IA que zotero-cli está disponible; puede ejecutar zotero-cli --help para descubrir comandos.

Verifica que funciona:

zotero-cli app ping
zotero-cli js "return Zotero.version"

Solución de problemas

Problema	Solución
`Cannot resolve Zotero profile directory`	Inicia Zotero al menos una vez primero
El plugin no aparece	Reinicia Zotero después de instalar el `.xpi`
`endpoint_active: false`	El plugin falló al cargar — reinstala vía la interfaz de Zotero
Windows: `pip` no reconocido	Cierra y reabre PowerShell después de instalar Python

Uso (Modo CLI)

Buscar y Navegar

zotero-cli item find "machine learning"
zotero-cli item search-fulltext "CRISPR"
zotero-cli collection tree

Importar

# Preferred agent ingest
zotero-cli --json add doi "10.1038/s41586-024-07871-6" --tag "review" --fetch-pdf
zotero-cli --json add arxiv 2602.02093 --collection COLLECTION_KEY
zotero-cli --json add file ./paper.pdf
zotero-cli --json add bibtex ./refs.bib --collection COLLECTION_KEY

# Lower-level import still available
zotero-cli import doi "10.1038/s41586-024-07871-6" --no-translator
zotero-cli --json item fetch-pdf ITEM_KEY --sources zotero,unpaywall,arxiv
zotero-cli --json collection fetch-pdfs COLLECTION_KEY --limit 20 --jsonl-progress

# DOCX one-shot citations
zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

# Audit recent write ops
zotero-cli --json audit tail --limit 20

Leer y Exportar

zotero-cli item get ITEM_KEY
zotero-cli item find "keyword" --scope fields
zotero-cli item export ITEM_KEY --format bibtex
zotero-cli export bib --items KEY1,KEY2 --output refs.bib
zotero-cli item citation ITEM_KEY
zotero-cli item context ITEM_KEY              # LLM-ready context
zotero-cli docx inspect-citations draft.docx  # detect Zotero/EndNote/static citation fields
zotero-cli docx validate-placeholders draft.docx
zotero-cli docx render-citations draft.docx --output draft-static.docx --force
zotero-cli docx doctor
zotero-cli docx insert-citations draft.docx --output draft-zotero.docx --force

Para flujos de trabajo DOCX escritos por IA, usa marcadores vinculados a Zotero como {{zotero:ITEMKEY}} o {{zotero:KEY1,KEY2}}, luego elige el modo de salida final (detalles y requisitos de software adicional están en Citas DOCX: estáticas vs dinámicas):

Citas estáticas: docx render-citations reemplaza los marcadores con texto de cita ordinario y añade una bibliografía estática. La ruta más fácil; sin LibreOffice. No se puede actualizar con el plugin de procesador de textos de Zotero.
Citas dinámicas: docx insert-citations convierte los marcadores en campos reales de Zotero/LibreOffice y crea o actualiza un campo de bibliografía actualizable. Requiere LibreOffice + add-in Zotero LO + Bridge además de Zotero Desktop.

Los agentes de IA deben preguntar al usuario qué modo quieren cuando la solicitud sea ambigua. Si el usuario solo quiere un DOCX final simple y no ha instalado LibreOffice, prefiere citas estáticas. Siempre ejecuta docx doctor antes de prometer conversión dinámica.

Protocolo recomendado para IA:

zotero-cli --json docx validate-placeholders <input.docx>
Si el usuario quiere referencias editables / soporte de actualización:
- zotero-cli --json docx doctor
- zotero-cli --json docx insert-citations <input.docx> --output <final.docx> --force
- Si la conversión falla, informa la capa que falló desde doctor y pregunta al usuario los siguientes pasos.
Si el usuario quiere salida estática o la dinámica no está disponible:
- zotero-cli --json docx render-citations <input.docx> --output <final.docx> --force

Mantén estos archivos solo como artefactos de entrega:

Borrador con marcadores (<input.docx>)
Borrador final convertido (<final.docx>)
No se debe exponer ningún DOCX intermedio a menos que --debug-dir se solicite explícitamente.

Soporte de plataforma para este flujo de trabajo opcional:

macOS: probado de extremo a extremo con apertura, conversión, guardado automáticos y salida DOCX compatible con Word.
Windows/Linux: el CLI base funciona, y docx doctor puede informar dependencias faltantes. La apertura/guardado automático completo de LibreOffice para citas DOCX dinámicas aún necesita validación real en escritorio Windows/Linux; los usuarios pueden necesitar abrir o guardar el documento de LibreOffice manualmente hasta que se verifique la automatización de la plataforma.

validate-placeholders, zoterify-preflight, y zoterify-probe son diagnósticos para configuración o casos de fallo. Añade --debug-dir solo cuando quieras artefactos JSON para solucionar problemas. docx prepare-zotero-import existe solo como comando de depuración experimental; no es un flujo de escritura soportado después de las pruebas con Zotero 9 + LibreOffice. docx insert-citations y docx render-citations son las dos salidas soportadas para la inserción de citas escritas por IA. item citation y item bibliography renderizan vistas previas estáticas; no son campos actualizables de Word/LibreOffice Zotero. La exportación BIB es una función de exportación separada y no forma parte del flujo de escritura DOCX.

Escribir y Gestionar

zotero-cli item update KEY --field title="New Title"
zotero-cli item tag KEY --add "important"
zotero-cli item attach KEY ./paper.pdf
zotero-cli item find-pdf KEY
zotero-cli note add KEY --text "My note"
zotero-cli sync

Avanzado

zotero-cli item search-annotations "risk"
zotero-cli item annotations KEY
zotero-cli item metrics KEY                   # NIH citation metrics
zotero-cli collection stats COLLECTION_KEY
zotero-cli js "return await Zotero.Items.getAll(1).then(i => i.length)"

Referencia completa de comandos: docs/COMMANDS.md

Funciones opcionales

Estas requieren servicios adicionales. Todo lo demás funciona sin ellos.

Búsqueda semántica

Cualquier endpoint /v1/embeddings compatible con OpenAI (Ollama, LM Studio, OpenAI, etc.).

zotero-cli item build-index                            # one-time
zotero-cli item semantic-search "cardiovascular risk"
zotero-cli item similar ITEM_KEY

Variable	Predeterminado	Descripción
`ZOTERO_EMBED_API`	`http://127.0.0.1:8080/v1/embeddings`	Endpoint de API de embeddings
`ZOTERO_EMBED_MODEL`	`nomic-embed-text`	Nombre del modelo
`ZOTERO_EMBED_KEY`	(vacío)	Clave API (si es necesaria)

Análisis de IA

export OPENAI_API_KEY=sk-...
zotero-cli item analyze ITEM_KEY --question "What are the main findings?"

Usuarios MCP heredados

El soporte MCP está congelado en v0.9.5. Para seguir usando el servidor MCP anterior, instala:

pip install "cli-anything-zotero[mcp]==0.9.5"

También puedes usar la rama legacy/mcp para instalaciones desde fuente. A partir de v1.0.0, el paquete mantenido instala solo superficies CLI/SDK y ya no proporciona el comando zotero-mcp.

Proyectos relacionados

Hay varias herramientas excelentes en el ecosistema Zotero. Cada una tiene fortalezas diferentes según tu caso de uso:

	cli-anything-zotero	zotero-mcp	zotero-cli-cc	pyzotero-cli
Enfoque	JS Bridge local	Web API + MCP	Web API + CLI	Web API + CLI
Mejor para	Local primero, control total	Flujos de trabajo nativos MCP	Investigación impulsada por agentes	Scripting y automatización
Operaciones de escritura	Local (sin clave API)	Vía Web API	Vía Web API	Vía Web API
Soporte MCP	Heredado vía v0.9.5	Sí	45 herramientas	No
CLI de terminal	Sí	No	Sí	Sí
Acceso JS de Zotero	Sí	No	No	No
Licencia	Apache 2.0	MIT	CC BY-NC 4.0	MIT

Licencia

Apache 2.0