MCP Server Zotero Dev

Dale a tu asistente de IA superpoderes para el desarrollo de plugins de Zotero

Arquitectura · Primeros pasos · Herramientas disponibles

Un servidor Model Context Protocol (MCP) que permite a asistentes de IA como Claude, Cursor y Windsurf crear, probar y depurar plugins de Zotero 7, 8, 9 y 10. Las capturas de pantalla, el estado del DOM, los registros de depuración y la ejecución de JavaScript dan a la IA un contexto rico para entender lo que está sucediendo, y herramientas para ayudarte a solucionarlo.

✨ Características

Related MCP server: Kaboom Browser AI Devtools MCP

🚀 Inicio rápido

Requisitos previos

• Node.js 20+ y npm

• Zotero 7+ — Funciona en todas las versiones de Zotero 7, 8, 9 y 10 (release, beta, dev)

• Para desarrollo de plugins: zotero-plugin-scaffold

1. Instala el servidor MCP

Usa install-mcp para añadir el servidor a tu asistente de IA:

npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-code

Clientes compatibles: claude-code, cursor, windsurf, vscode, cline, roo-cline, claude, zed, goose, warp, codex

npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-code

npx -y install-mcp @introfini/mcp-server-zotero-dev --client cursor

npx -y install-mcp @introfini/mcp-server-zotero-dev --client vscode

npx -y install-mcp @introfini/mcp-server-zotero-dev --client windsurf

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.1"],
      "env": {
        "ZOTERO_RDP_PORT": "6100"
      }
    }
  }
}

Versión y actualizaciones: fija una versión exacta como se muestra arriba. Un npx <pkg> sin versión seguirá ejecutando lo que npx haya cacheado y no recogerá las nuevas versiones, así que incluye siempre una versión y -y (sin -y, npx se queda esperando un aviso de instalación). Sube la versión fijada para actualizar, o usa @latest para obtener siempre la más reciente al inicio (se actualiza automáticamente, pero una versión mala se ejecutaría automáticamente y añade una comprobación de registro en cada inicio). Ten en cuenta que install-mcp puede escribir una configuración sin -y o sin versión, así que la configuración manual de arriba es la vía más robusta.

Reinicia tu asistente de IA después de añadir la configuración.

2. Instala el plugin MCP Bridge en Zotero

Descarga zotero-mcp-bridge.xpi e instálalo:

1. En Zotero: Herramientas → Plugins

2. Haz clic en ⚙️ → Instalar plugin desde archivo

3. Selecciona el archivo .xpi descargado

4. Reinicia Zotero

Este plugin ligero habilita el Protocolo de Depuración Remota cuando Zotero se inicia. Solo necesita instalarse una vez y funciona en todas las versiones de Zotero 7+ (release, beta y dev).

3. ¡Empieza a desarrollar!

Simplemente abre Zotero normalmente y pide a tu asistente de IA:

"Toma una captura de pantalla de Zotero y lista los plugins instalados"

¡Eso es todo! Sin banderas de lanzamiento especiales, sin configuración. 🎉

🧰 Herramientas disponibles (28 en total)

Objetivos de captura: ventana principal, preferencias, lector de PDF, diálogos o cualquier elemento por selector. Usa highlightSelector para añadir un borde rojo antes de la captura.

La resolución intenta primero el DOM ligero, luego atraviesa las shadow roots abiertas (los elementos personalizados XUL de Zotero mantienen los internos en el shadow DOM). Limitación: no puede descartar un diálogo modal nativo bloqueante (Services.prompt.confirmEx) — su bucle modal anidado bloquea el hilo de evaluación en el que se ejecutan estas herramientas.

Ejemplos: Zotero.Items.getAll(1), Zotero.Prefs.get('export.quickCopy.setting'), ZoteroPane.getSelectedItems()

Consejo: usa zotero_inspect_object para explorar las APIs antes de escribir código. Usa zotero_search_prefs para descubrir claves de preferencias.

Nota: el acceso a la base de datos es de solo lectura y requiere que Zotero esté cerrado, o usa una copia de la base de datos.

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant                             │
│                  (Claude, Cursor, Windsurf)                     │
└─────────────────────────┬───────────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                  MCP Server (Node.js/TypeScript)                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Scaffold   │  │     RDP      │  │      Database        │   │
│  │  Integration │  │    Client    │  │      Reader          │   │
│  └──────────────┘  └──────┬───────┘  └──────────────────────┘   │
└─────────────────────────────┼───────────────────────────────────┘
                              │ Firefox RDP (port 6100)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Zotero Application                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │            MCP Bridge for Zotero                         │   │
│  │         Starts DevToolsServer on launch                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Firefox DevTools Server (built-in)          │   │
│  │           JS Execution • DOM • Console • Screenshots     │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Your Plugin (dev)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

¿Por qué este enfoque?

• ✅ Plugin ligero — Solo habilita RDP, Firefox DevTools hace el resto

• ✅ Cero configuración tras la instalación — Solo abre Zotero normalmente, sin banderas especiales

• ✅ Contexto rico para la IA — Las capturas de pantalla, el DOM y los registros ayudan a la IA a entender el estado de tu plugin

• ✅ Recarga en caliente — Se integra con zotero-plugin-scaffold para retroalimentación instantánea

• ✅ Acceso completo a Zotero — Ejecuta cualquier API de Zotero en el contexto privilegiado

• ✅ Multiplataforma — Funciona en Linux, Windows, macOS

🔧 Variables de entorno

🔌 Cambiar el puerto RDP

El puente escucha en el puerto 6100 por defecto. Solo necesitas cambiarlo si ejecutas dos instancias de Zotero al mismo tiempo (un perfil normal y uno de desarrollo, por ejemplo), o si otro proceso ya ocupa el 6100.

El puerto vive en ambos lados del puente, y ambos tienen que estar de acuerdo.

1. Lado de Zotero — establece la preferencia del plugin:

1. Configuración → Avanzado → Editor de configuración, y acepta la advertencia

2. Busca extensions.mcp-rdp.port

3. Si no existe, créala: selecciona Número, nómbrala extensions.mcp-rdp.port, e introduce tu puerto

4. Reinicia Zotero — el listener solo se abre al inicio

Cuidado con el tipo. El Editor de configuración preselecciona Booleano. Crear la preferencia sin cambiar a Número almacena true en lugar de un puerto, y Zotero entonces abre el puente en un pipe local en lugar de un puerto TCP — el registro de depuración informa de éxito mientras ningún cliente MCP puede conectarse.

2. Lado del cliente — establece ZOTERO_RDP_PORT al mismo valor en la configuración de tu cliente MCP:

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.2"],
      "env": {
        "ZOTERO_RDP_PORT": "6101"
      }
    }
  }
}

Cambia ambos o ninguno. Si solo cambias un lado, el puente se desconecta: Zotero escucha en un puerto mientras el cliente sigue marcando el otro.

Ejecutar realmente dos instancias

Al iniciar Zotero por segunda vez, obtienes la ventana que ya tienes: como Firefox, reenvía a la instancia en ejecución en lugar de iniciar otra. Una segunda instancia necesita su propio perfil y -no-remote:

# macOS; adjust the binary path on Windows/Linux
MOZ_NO_REMOTE=1 "/Applications/Zotero.app/Contents/MacOS/zotero" -P <profile-name> -no-remote

Dale a ese perfil su propio extensions.mcp-rdp.port y los dos puentes no se estorbarán. Verificado con 9.0.6 en 6100 y 10.0-beta.22 en 6101 al mismo tiempo.

Requiere el plugin MCP Bridge 1.0.5 o posterior. En 1.0.4 y anteriores, extensions.mcp-rdp.port se leía en la rama de preferencias incorrecta y se ignoraba silenciosamente, por lo que el puente permanecía en 6100 sin importar lo que configuraras. Si configuraste un puerto personalizado con una versión anterior, se almacena como extensions.zotero.extensions.mcp-rdp.port — ese nombre sigue funcionando, pero prefiere el anterior.

Deshabilitar el puente

Establece extensions.mcp-rdp.enabled en false (Booleano) en el Editor de Configuración y reinicia Zotero. El plugin permanece instalado pero no abre ningún listener, y ningún cliente MCP puede acceder a Zotero hasta que lo vuelvas a poner en true.

📸 Ejemplos de capturas de pantalla

// Capture main Zotero window
await zotero_screenshot({ target: 'main-window' });

// Capture your plugin's panel with highlight
await zotero_screenshot({
  target: 'element',
  selector: '#my-plugin-panel',
  highlightSelector: '#my-plugin-button'
});

// Capture a specific window by ID (use zotero_list_windows to find IDs)
await zotero_screenshot({
  target: 'window',
  windowId: 12345
});

// Capture element after triggering UI action
await zotero_execute_js({ code: 'document.querySelector("#menu").click()' });
await zotero_screenshot({ target: 'element', selector: 'menupopup[state="open"]' });

🧑💻 Desarrollo

# Clone and install
git clone https://github.com/introfini/mcp-server-zotero-dev.git
cd mcp-server-zotero-dev
npm install

# Build everything
npm run build

# Build individual packages
npm run build:server
npm run build:plugin

# Run tests
npm test

# Development mode (watch)
npm run dev

mcp-server-zotero-dev/
├── packages/
│   ├── mcp-server/               # MCP server (npm package)
│   │   ├── src/
│   │   │   ├── index.ts          # MCP server entry
│   │   │   ├── rdp/              # RDP client
│   │   │   ├── tools/            # Tool implementations
│   │   │   └── prompts/          # Slash commands
│   │   └── package.json
│   │
│   └── zotero-plugin-mcp-rdp/    # Tiny Zotero plugin (.xpi)
│       ├── src/
│       │   └── bootstrap.js      # Starts RDP server (shipped verbatim)
│       ├── addon/
│       │   └── manifest.json
│       └── package.json
│
├── docs/                         # Documentation
└── package.json                  # Monorepo root

📚 Recursos

• Arquitectura y aprendizajes técnicos — Inmersión profunda en el protocolo RDP, la jerarquía de actores y los errores comunes

• Desarrollo de plugins de Zotero — Documentación oficial

• Zotero 10 para desarrolladores — Guía de migración para la última versión principal

• Zotero 7 para desarrolladores — Guía de migración

• zotero-plugin-scaffold — Herramientas de compilación

• zotero-plugin-template — Plantilla inicial

• zotero-plugin-toolkit — Ayudantes de API

• Protocolo RDP de Firefox — Documentación del protocolo

🤝 Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para la configuración, las convenciones de prueba y las reglas específicas del código que vale la pena conocer antes de empezar.

La versión corta:

1. Sigue los patrones de código existentes

2. Añade pruebas para nuevas funciones, y omite en lugar de fallar cuando Zotero no está en ejecución

3. Actualiza la documentación

4. No hay CI, así que ejecuta npm run build, npm run typecheck, npm run lint y npm test tú mismo, y menciona en el PR contra qué versión de Zotero lo verificaste

📄 Licencia

MIT © introfini

Agradecimientos

• Construido para la comunidad de desarrolladores de plugins de Zotero

• Se integra con zotero-plugin-scaffold por @windingwind

• Aprovecha el RDP de Firefox DevTools para una comunicación fiable