Zotero Local MCP Bridge
Usa un endpoint MCP alojado en un plugin de Zotero para que agentes locales gestionen de forma segura una biblioteca local de Zotero.
Documentación
Zotero Local MCP Bridge
Usa un endpoint MCP alojado en un plugin de Zotero para que los agentes locales gestionen una biblioteca local de Zotero de forma segura.
AGPL-3.0-or-later · Versión del plugin 0.1.60 · Zotero 9.x · MCP alojado en plugin · Acceso de bucle local
简体中文 · English
Qué hace · Qué no hace · Alcance · Cómo funciona · Inicio rápido · Ejemplos · Apoyar al autor · Licencia
✨ Qué hace
Zotero Local MCP Bridge permite que los agentes compatibles con MCP gestionen una biblioteca local de Zotero a través del propio Zotero. No es un script de base de datos que omita a Zotero. Es un punto de entrada MCP local que se ejecuta dentro del plugin de Zotero.
| Área | Capacidad |
|---|---|
| 📚 Elementos y colecciones | Leer, buscar, crear y editar elementos; comprobar por lotes si ya existen registros DOI; gestionar por lotes la pertenencia a colecciones de nivel superior o subcolecciones |
| 📎 Archivos adjuntos | Añadir, mover, renombrar e inspeccionar archivos adjuntos; importar uno o varios archivos PDF/EPUB y usar el reconocimiento de metadatos integrado de Zotero y la lógica de renombrado de archivos adjuntos |
| 📝 Anotaciones y citas | Leer, crear y actualizar anotaciones PDF compatibles; formatear citas y bibliografías mediante Zotero |
| 🔁 Importación y exportación | Importar y exportar BibTeX, RIS y CSL JSON |
| 🔎 Búsqueda | Usar flujos de búsqueda básica, búsqueda avanzada y lectura/actualización de búsquedas guardadas |
| 🛡️ Flujo de seguridad | Aplicar dry-run en todas las escrituras; admitir aprobación, auditoría, copia de seguridad a nivel de archivo y deshacer |
| 🧩 Duplicados | Encontrar duplicados y ejecutar flujos controlados de fusión de duplicados |
[!NOTE] Las escrituras no se ejecutan de inmediato. El agente primero recibe un plan de dry-run, advertencias, objetivos afectados y datos de confirmación. En los modos de aprobación, la ejecución debe esperar la aprobación del usuario.
🚫 Qué no hace
| No compatible | Motivo |
|---|---|
| Gestionar bibliotecas de Zotero en línea | Este proyecto no escribe a través de la API web de Zotero ni gestiona cuentas remotas de Zotero |
Usar ZOTERO_API_KEY | Este proyecto no solicita, lee ni almacena una clave API de Zotero |
Escribir directamente en zotero.sqlite | Los cambios deben pasar por las API internas de Zotero |
| Exponer evaluación arbitraria de JavaScript | La gestión ordinaria debe provenir de la tabla de comandos del plugin |
| Gestionar bibliotecas de grupo | El alcance público actual cubre solo bibliotecas de usuario locales |
| Eliminación permanente o vaciar la papelera | Los flujos actuales similares a eliminación usan la papelera de Zotero o fusión controlada, no borrado irrecuperable |
| Eliminar directamente archivos adjuntos existentes | Las operaciones con archivos adjuntos deben respetar los límites de copia de seguridad/deshacer y seguridad |
📍 Alcance
Este plugin está diseñado para Zotero Desktop y un cliente MCP local en la misma máquina. El endpoint MCP se registra en el servidor conector local de Zotero y usa únicamente acceso de bucle local.
| Elemento | Configuración actual |
|---|---|
| Ubicación de ejecución | Dentro del plugin de Zotero |
| Endpoint | http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp |
| Alcance de la biblioteca | Biblioteca de usuario local |
| Ruta de escritura | API internas de Zotero |
| Modelo de red | Bucle local, sin escrituras en la nube |
| Auditoría y copia de seguridad | Deben permanecer fuera del perfil de Zotero, el directorio de datos de Zotero, la raíz de archivos adjuntos vinculados y los directorios de archivos adjuntos |
El modo de ejecución se configura en Settings -> Zotero Local MCP Bridge:
| Modo | Comportamiento |
|---|---|
readonly | Bloquea todas las escrituras |
askforapprove | El agente solicita aprobación al usuario después del dry-run |
yolo | Las escrituras ordinarias pueden ejecutarse automáticamente cuando el plan lo permite; las operaciones de alto riesgo o futuras irrecuperables aún requieren confirmación explícita |
⚙️ Cómo funciona
MCP-capable agent
-> MCP tool call
-> Zotero local connector server
-> Zotero Local MCP Bridge plugin endpoint
-> plugin command table
-> Zotero internal API
El endpoint MCP está alojado dentro del plugin de Zotero:
http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
No hay ningún proceso MCP separado de Node, Python o sidecar que iniciar. Iniciar Zotero inicia el endpoint del plugin. Cerrar Zotero lo detiene. La compilación de lanzamiento expone herramientas MCP, no el antiguo endpoint de comandos privado.
Codex y Claude Code pueden conectarse directamente al endpoint MCP Streamable HTTP. OpenCode y otros clientes con soporte stdio pero sin soporte Streamable HTTP pueden usar el adaptador stdio independiente. El adaptador se ejecuta en el lado del agente, permanece fuera del XPI y nunca toca la base de datos de Zotero.
🚀 Inicio rápido
1. Descargar los archivos de lanzamiento
Descarga desde GitHub Releases:
| Archivo | Propósito |
|---|---|
zotero-local-mcp-bridge.xpi | Plugin de Zotero |
zotero-local-mcp-bridge-<version>.mcpb | Paquete MCP de Claude Desktop para macOS y Windows |
| Skill en inglés | Para agentes de habla inglesa |
| Skill en chino | Para agentes de habla china |
2. Instalar el plugin de Zotero
Abre el gestor de plugins de Zotero:
Tools -> Plugins
Arrastra zotero-local-mcp-bridge.xpi a la ventana del gestor de plugins, confirma la instalación cuando se solicite y reinicia Zotero.
3. Elegir el modo de ejecución
Abre:
Settings -> Zotero Local MCP Bridge
Para el primer uso, comienza con readonly o askforapprove. Usa yolo solo después de comprender el comportamiento de dry-run, aprobación, auditoría y copia de seguridad.
4. Conectar el cliente MCP
Los agentes pueden conectarse mediante stdio o Streamable HTTP. Los usuarios de Claude Desktop en macOS o Windows pueden instalar el adaptador MCPB empaquetado.
Opción A: MCP stdio
Instala el adaptador npm:
npm install -g zotero-local-mcp-bridge-stdio-adapter
Luego configura MCP stdio en tu agente:
[mcp_servers.zotero-local-mcp-bridge]
command = "zotero-local-mcp-bridge-stdio"
args = []
startup_timeout_sec = 20
tool_timeout_sec = 120
Configuración genérica de MCP stdio:
{
"mcpServers": {
"zotero-local-mcp-bridge": {
"type": "stdio",
"command": "zotero-local-mcp-bridge-stdio",
"args": []
}
}
}
También puedes usar npx sin instalación global:
{
"mcpServers": {
"zotero-local-mcp-bridge": {
"type": "stdio",
"command": "npx",
"args": ["-y", "zotero-local-mcp-bridge-stdio-adapter"]
}
}
}
El adaptador stdio es una capa de compatibilidad iniciada por la sesión del agente. Reenvía las solicitudes MCP stdio al endpoint HTTP MCP del plugin de Zotero. No es el plugin de Zotero en sí y no se inicia con Zotero.
Antes de editar una configuración de agente, verifica el plugin instalado y el endpoint MCP:
zotero-local-mcp-bridge-stdio doctor
El comando de una sola ejecución verifica la inicialización de MCP y el descubrimiento de herramientas, luego imprime la versión del plugin detectada, el recuento de herramientas y las configuraciones listas para copiar de Codex, Claude Code y OpenCode. No modifica la configuración del agente.
Consulta la matriz de compatibilidad de clientes para conocer las limitaciones de Codex, Claude Code, OpenCode, Claude Desktop y ChatGPT actual.
Opción B: MCP HTTP
Si tu agente admite Streamable HTTP / HTTP MCP, puedes omitir el paquete npm y conectarte directamente al endpoint del plugin de Zotero:
http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
Ejemplo de Codex:
[mcp_servers.zotero-local-mcp-bridge]
url = "http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 120
Ejemplo de Claude Code:
claude mcp add --transport http zotero-local-mcp-bridge http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
Opción C: Claude Desktop MCPB
Instala zotero-local-mcp-bridge-<version>.mcpb en Claude Desktop en macOS o Windows. El MCPB contiene el adaptador de compatibilidad stdio, no el plugin de Zotero; instala el XPI primero y mantén Zotero abierto. Consulta Configuración de Claude Desktop.
5. Instalar el skill correspondiente
| Idioma | Skill |
|---|---|
| Inglés | skills/zotero-local-mcp-bridge/SKILL.md |
| Chino | skills/zotero-local-mcp-bridge-zh-cn/SKILL.md |
Indica al agente que use Zotero a través de Zotero Local MCP Bridge. Cuando se requiera aprobación, el agente debe describir brevemente la operación pendiente y esperar la aprobación del usuario.
6. Ejecutar la primera consulta de solo lectura
Pregunta al agente:
List my Zotero collection tree without making changes.
El agente debe llamar a zotero_collection_get_tree con libraryScope=local-user. Esta consulta no requiere aprobación de escritura.
🧪 Ejemplos
| Pide al agente | Comportamiento esperado |
|---|---|
| Listar mi árbol de colecciones de Zotero | Consulta de solo lectura, sin confirmación de escritura |
| Comprobar qué valores DOI ya existen en mi biblioteca | Ejecutar una búsqueda por lotes y devolver los elementos coincidentes, las claves de elementos reutilizables y los valores DOI no coincidentes |
| Añadir estos elementos existentes a "Proyecto actual / Cola de lectura" | Usar un dry-run, una aprobación cuando sea necesario y una escritura por lotes omitiendo los miembros existentes |
| Crear una subcolección "Cola de lectura" bajo "Proyecto actual" | Dry-run primero, luego solicitar aprobación |
| Añadir este archivo PDF adjunto a este elemento | Resolver el elemento y la ruta del archivo, luego ejecutar dry-run de la operación de archivo adjunto |
| Importar este PDF y recuperar metadatos automáticamente | Dry-run primero, luego usar el flujo de reconocimiento integrado de Zotero para crear el elemento principal y renombrar el archivo adjunto según las preferencias |
| Importar estos PDF y recuperar metadatos automáticamente | Usar la herramienta de reconocimiento por lotes con un dry-run, una aprobación y una ejecución |
| Exportar los elementos seleccionados como BibTeX | Exportación de solo lectura, sin confirmación de escritura |
| Formatear una bibliografía con un estilo elegido | Usar el formateador de citas de Zotero |
En modo de aprobación, una sola operación de escritura debe interactuar a través del agente de esta manera:
I am about to create a subcollection named "Reading Queue" under "Current Project". Approve execution?
Las operaciones pendientes múltiples usan una tabla numerada, para que el usuario pueda aprobar todas las operaciones o aprobar solo números seleccionados:
The following operations need approval:
| No. | Operation |
|---:|---|
| 1 | Move subcollection "Temporary" under "Old Project" to Zotero trash |
| 2 | Merge duplicate items "Smith 2024" and "Smith 2024 copy" |
| 3 | Add "Zotero MCP design notes" to "Current Project / Reading Queue" |
El usuario puede responder "aprobar todas", o responder "aprobar 1 y 3, rechazar 2".
Si este proyecto ayuda en tu flujo de trabajo, considera marcar el repositorio con una estrella o abrir un issue enfocado con comentarios reproducibles.
❤️ Apoyar al autor
📄 Licencia
Zotero Local MCP Bridge está licenciado bajo AGPL-3.0-or-later. Consulta LICENSE.