MCP Server Zotero Dev

Verleihen Sie Ihrem KI-Assistenten Superkräfte für die Zotero-Plugin-Entwicklung

Architektur · Erste Schritte · Verfügbare Tools

Ein Model Context Protocol (MCP)-Server, der KI-Assistenten wie Claude, Cursor und Windsurf in die Lage versetzt, Zotero-Plugins für Version 7, 8, 9 und 10 zu erstellen, zu testen und zu debuggen. Screenshots, DOM-Zustand, Debug-Logs und JavaScript-Ausführung geben der KI reichhaltigen Kontext, um zu verstehen, was passiert – und Tools, um Ihnen bei der Behebung zu helfen.

✨ Funktionen

Related MCP server: Kaboom Browser AI Devtools MCP

🚀 Schnellstart

Voraussetzungen

• Node.js 20+ und npm

• Zotero 7+ — Funktioniert mit allen Zotero-7-, 8-, 9- und 10-Builds (Release, Beta, Dev)

• Für die Plugin-Entwicklung: zotero-plugin-scaffold

1. MCP-Server installieren

Verwenden Sie install-mcp, um den Server zu Ihrem KI-Assistenten hinzuzufügen:

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

Unterstützte Clients: 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

Fügen Sie Folgendes zu Ihrer MCP-Client-Konfiguration hinzu:

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

Version & Updates: Pinne eine exakte Version an, wie oben gezeigt. Ein bloßes npx <pkg> (ohne Version) verwendet weiterhin das, was npx zwischengespeichert hat, und übernimmt keine neuen Releases. Geben Sie daher immer eine Version und -y an (ohne -y hängt npx und wartet auf eine Installationsaufforderung). Erhöhen Sie die gepinnte Version, um ein Upgrade durchzuführen, oder verwenden Sie @latest, um beim Start immer die neueste Version abzurufen (automatische Updates, aber ein fehlerhaftes Release würde automatisch ausgeführt und es fügt bei jedem Start eine Registry-Überprüfung hinzu). Beachten Sie, dass install-mcp möglicherweise eine Konfiguration ohne -y oder Version schreibt. Die manuelle Konfiguration oben ist daher der robusteste Weg.

Starten Sie Ihren KI-Assistenten neu, nachdem Sie die Konfiguration hinzugefügt haben.

2. MCP-Bridge-Plugin in Zotero installieren

Laden Sie zotero-mcp-bridge.xpi herunter und installieren Sie es:

1. In Zotero: Extras → Plugins

2. Klicken Sie auf ⚙️ → Plugin aus Datei installieren

3. Wählen Sie die heruntergeladene .xpi-Datei aus

4. Starten Sie Zotero neu

Dieses schlanke Plugin aktiviert das Remote-Debugging-Protokoll beim Start von Zotero. Es muss nur einmal installiert werden und funktioniert mit allen Zotero-7+-Builds (Release, Beta und Dev).

3. Entwickeln Sie los!

Öffnen Sie einfach Zotero normal und fragen Sie Ihren KI-Assistenten:

„Machen Sie einen Screenshot von Zotero und listen Sie installierte Plugins auf"

Das war's! Keine speziellen Startflags, keine Konfiguration. 🎉

🧰 Verfügbare Tools (insgesamt 28)

Screenshot-Ziele: Hauptfenster, Einstellungen, PDF-Reader, Dialoge oder jedes Element per Selektor. Verwenden Sie highlightSelector, um vor der Aufnahme einen roten Rahmen hinzuzufügen.

Die Auflösung versucht zuerst das Light DOM, dann durchdringt sie offene Shadow-Roots (die XUL-Custom-Elemente von Zotero halten Interna im Shadow DOM). Einschränkung: Ein blockierendes natives modales Dialogfeld (Services.prompt.confirmEx) kann nicht geschlossen werden – seine verschachtelte modale Schleife blockiert den Eval-Thread, auf dem diese Tools laufen.

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

Tipp: Verwenden Sie zotero_inspect_object, um APIs zu erkunden, bevor Sie Code schreiben. Verwenden Sie zotero_search_prefs, um Einstellungsschlüssel zu entdecken.

Hinweis: Der Datenbankzugriff ist schreibgeschützt und erfordert, dass Zotero geschlossen ist, oder verwendet eine Kopie der Datenbank.

🏗️ Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        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)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Warum dieser Ansatz?

• ✅ Schlankes Plugin — Aktiviert nur RDP, Firefox DevTools erledigt den Rest

• ✅ Null-Konfiguration nach der Installation — Öffnen Sie Zotero einfach normal, keine speziellen Flags

• ✅ Reichhaltiger KI-Kontext — Screenshots, DOM und Logs helfen der KI, den Zustand Ihres Plugins zu verstehen

• ✅ Hot Reload — Integration mit zotero-plugin-scaffold für sofortiges Feedback

• ✅ Voller Zotero-Zugriff — Jede Zotero-API im privilegierten Kontext ausführen

• ✅ Plattformübergreifend — Funktioniert unter Linux, Windows, macOS

🔧 Umgebungsvariablen

🔌 Den RDP-Port ändern

Die Bridge lauscht standardmäßig auf Port 6100. Sie müssen ihn nur ändern, wenn Sie zwei Zotero-Instanzen gleichzeitig ausführen (z. B. ein normales Profil und ein Entwicklungsprofil) oder wenn ein anderer Prozess bereits 6100 belegt.

Der Port liegt auf beiden Seiten der Bridge, und beide müssen sich darauf einigen.

1. Zotero-Seite — die Plugin-Einstellung festlegen:

1. Einstellungen → Erweitert → Konfigurationseditor und die Warnung akzeptieren

2. Nach extensions.mcp-rdp.port suchen

3. Wenn sie nicht existiert, erstellen Sie sie: Zahl auswählen, sie extensions.mcp-rdp.port nennen und Ihren Port eingeben

4. Zotero neu starten — der Listener öffnet nur beim Start

Achten Sie auf den Typ. Der Konfigurationseditor wählt standardmäßig Boolean aus. Wenn Sie die Einstellung erstellen, ohne auf Zahl zu wechseln, wird true statt eines Ports gespeichert, und Zotero öffnet die Bridge dann über eine lokale Pipe statt über einen TCP-Port – das Debug-Log meldet Erfolg, während kein MCP-Client eine Verbindung herstellen kann.

2. Client-Seite — setzen Sie ZOTERO_RDP_PORT in Ihrer MCP-Client-Konfiguration auf denselben Wert:

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

Ändern Sie beide oder keinen. Wenn Sie nur eine Seite ändern, wird die Bridge getrennt: Zotero lauscht auf einem Port, während der Client weiterhin den anderen anwählt.

Tatsächlich zwei Instanzen ausführen

Wenn Sie Zotero ein zweites Mal starten, erhalten Sie das Fenster, das Sie bereits haben – wie Firefox leitet es an die laufende Instanz weiter, anstatt eine weitere zu starten. Eine zweite Instanz benötigt ein eigenes Profil und -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

Geben Sie diesem Profil einen eigenen extensions.mcp-rdp.port und die beiden Bridges bleiben sich aus dem Weg. Verifiziert mit 9.0.6 auf 6100 und 10.0-beta.22 auf 6101 gleichzeitig.

Erfordert MCP Bridge Plugin 1.0.5 oder neuer. In 1.0.4 und früher wurde extensions.mcp-rdp.port unter dem falschen Präferenzzweig gelesen und stillschweigend ignoriert, sodass die Bridge unabhängig von Ihrer Einstellung auf 6100 blieb. Wenn Sie einen benutzerdefinierten Port für einen älteren Build konfiguriert haben, wird er als extensions.zotero.extensions.mcp-rdp.port gespeichert – dieser Name funktioniert weiterhin, aber bevorzugen Sie den obigen.

Deaktivieren der Bridge

Setzen Sie extensions.mcp-rdp.enabled auf false (Boolean) im Config Editor und starten Sie Zotero neu. Das Plugin bleibt installiert, öffnet aber keinen Listener, und kein MCP-Client kann Zotero erreichen, bis Sie es wieder auf true setzen.

📸 Screenshot-Beispiele

// 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"]' });

🧑💻 Entwicklung

# 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

📚 Ressourcen

• Architektur & technische Erkenntnisse — Tiefer Einblick in das RDP-Protokoll, die Akteur-Hierarchie und häufige Fallstricke

• Zotero Plugin Entwicklung — Offizielle Dokumentation

• Zotero 10 für Entwickler — Migrationsleitfaden für die neueste Hauptversion

• Zotero 7 für Entwickler — Migrationsleitfaden

• zotero-plugin-scaffold — Build-Werkzeuge

• zotero-plugin-template — Startvorlage

• zotero-plugin-toolkit — API-Helfer

• Firefox RDP Protokoll — Protokolldokumentation

🤝 Mitwirken

Beiträge sind willkommen. Siehe CONTRIBUTING.md für Einrichtung, Testkonventionen und die codebasespezifischen Regeln, die Sie vor dem Start kennen sollten.

Die Kurzfassung:

1. Befolgen Sie bestehende Codemuster

2. Fügen Sie Tests für neue Funktionen hinzu und überspringen Sie sie, anstatt sie fehlschlagen zu lassen, wenn Zotero nicht läuft

3. Aktualisieren Sie die Dokumentation

4. Es gibt kein CI, führen Sie also npm run build, npm run typecheck, npm run lint und npm test selbst aus und geben Sie im PR an, welche Zotero-Version Sie getestet haben

📄 Lizenz

MIT © introfini

Danksagungen

• Entwickelt für die Zotero Plugin-Entwickler-Community

• Integriert mit zotero-plugin-scaffold von @windingwind

• Nutzt Firefox DevTools RDP für zuverlässige Kommunikation