MCP Bridge for Zotero

Servidor MCP Zotero Dev

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

Arquitectura · Primeros pasos · Herramientas disponibles

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a asistentes de IA como Claude, Cursor y Windsurf crear, probar y depurar plugins de Zotero 7, 8, 9 y 10. Capturas de pantalla, estado del DOM, registros de depuración y ejecución de JavaScript brindan al asistente de IA un contexto rico para comprender lo que está sucediendo, además de herramientas para ayudarte a solucionarlo.

✨ Características

🚀 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. Instalar el servidor MCP

Usa install-mcp para agregar 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

{
  "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 (sin número de versión) seguirá ejecutando lo que npx haya almacenado en caché y no recogerá nuevas versiones, así que incluye siempre una versión y -y (sin -y, npx se queda esperando un aviso de instalación). Aumenta la versión fijada para actualizar, o usa @latest para obtener siempre la más reciente al iniciar (actualizaciones automáticas, pero una versión defectuosa se ejecutaría automáticamente y añade una comprobación del registro en cada inicio). Ten en cuenta que install-mcp puede escribir una configuración sin -y o sin versión, por lo que la configuración manual anterior es la ruta más robusta.

Reinicia tu asistente de IA después de agregar la configuración.

2. Instalar 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 pídele a tu asistente de IA:

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

¡Eso es todo! Sin indicadores de inicio especiales, sin configuración. 🎉

🧰 Herramientas disponibles (28 en total)

🏗️ 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 después de la instalación — Solo abre Zotero normalmente, sin indicadores especiales
• ✅ Contexto rico para la IA — Las capturas de pantalla, el DOM y los registros ayudan a la IA a comprender 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 y macOS

🔧 Variables de entorno

🔌 Cambiar el puerto RDP

El puente escucha en el puerto 6100 de forma predeterminada. 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 deben coincidir.

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 ingresa 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 una tubería local en lugar de un puerto TCP — el registro de depuración informa é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. Mover solo un lado desconecta el puente: Zotero escucha en un puerto mientras el cliente sigue marcando el otro.

Ejecutar dos instancias realmente

Iniciar Zotero por segunda vez te entrega 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 interferirán entre sí. Verificado con 9.0.6 en el 6100 y 10.0-beta.22 en el 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 bajo la rama de preferencias incorrecta y se ignoraba silenciosamente, por lo que el puente permanecía en el 6100 sin importar lo que configuraras. Si configuraste un puerto personalizado contra 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 alcanzar Zotero hasta que lo vuelvas a establecer 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 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! Por favor:

1. Sigue los patrones de código existentes
2. Añade pruebas para nuevas funcionalidades
3. Actualiza la documentación
4. Asegúrate de que npm test y npm run lint pasen

📄 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