io.github.introfini/mcp-server-zotero-dev

Official

by introfini · TypeScript

MCP server enabling AI assistants to build, test, and debug Zotero plugins

Build, test, and debug Zotero plugins with AI assistance.

Topics

mcpmcp-clientmcp-servermcp-toolszoterozotero-addonzotero-apizotero-pluginzotero-plugin-developmentzotero7zotero8zotero9

README.md16 KBView on GitHub

MCP Server Zotero Dev

Give your AI assistant superpowers for Zotero plugin development

Architecture · Getting Started · Available Tools

A Model Context Protocol (MCP) server that enables AI assistants like Claude, Cursor, and Windsurf to build, test, and debug Zotero 7, 8, and 9 plugins. Screenshots, DOM state, debug logs, and JavaScript execution give the AI rich context to understand what's happening—and tools to help you fix it.

✨ Features

Category	Capabilities
🎯 UI Inspection	Screenshots, DOM tree, element finding, computed styles
🖱️ UI Interaction	Click elements and type text (shadow-DOM aware)
💻 JS Execution	Run code in Zotero context, inspect APIs, test snippets
🔧 Build Tools	Scaffold integration for build, serve, hot reload
📋 Logs & Errors	Stream debug output, error console, watch for issues
🗃️ Database	Read-only access to zotero.sqlite for debugging
🔌 Plugin Management	Install, reload, list plugins

🚀 Quick Start

Prerequisites

Node.js 20+ and npm
Zotero 7+ — Works on all Zotero 7, 8, and 9 builds (release, beta, dev)
For plugin development: zotero-plugin-scaffold

1. Install MCP Server

Use install-mcp to add the server to your AI assistant:

bash

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

Supported clients: claude-code, cursor, windsurf, vscode, cline, roo-cline, claude, zed, goose, warp, codex

<details> <summary>Claude Code</summary>

bash

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

</details> <details> <summary>Cursor</summary>

bash

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

</details> <details> <summary>VS Code / Copilot</summary>

bash

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

</details> <details> <summary>Windsurf</summary>

bash

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

</details> <details> <summary>Manual Configuration</summary>

Add to your MCP client config:

json

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

</details>

Version & updates: pin an exact version as shown above. A bare npx <pkg> (no version) keeps running whatever npx cached and won't pick up new releases, so always include a version and -y (without -y, npx hangs waiting for an install prompt). Bump the pinned version to upgrade, or use @latest to always fetch the newest at launch (auto-updates, but a bad release would run automatically and it adds a registry check on every start). Note that install-mcp may write a config without -y or a version, so the manual configuration above is the most robust path.

Restart your AI assistant after adding the configuration.

2. Install MCP Bridge Plugin in Zotero

Download zotero-mcp-bridge.xpi and install:

In Zotero: Tools → Plugins
Click ⚙️ → Install Plugin From File
Select the downloaded .xpi file
Restart Zotero

This lightweight plugin enables the Remote Debugging Protocol when Zotero starts. It only needs to be installed once and works on all Zotero 7+ builds (release, beta, and dev).

3. Start Developing!

Just open Zotero normally and ask your AI assistant:

"Take a screenshot of Zotero and list installed plugins"

That's it! No special launch flags, no configuration. 🎉

🧰 Available Tools (28 total)

<details> <summary>UI Inspection — Screenshots, DOM, styles</summary>

Tool	Description
`zotero_screenshot`	Capture window, element, or region screenshots
`zotero_inspect_element`	Find elements by CSS selector
`zotero_get_dom_tree`	Get DOM structure of a window/panel
`zotero_get_styles`	Get computed CSS styles for element
`zotero_list_windows`	List all open Zotero windows

Screenshot Targets: Main window, preferences, PDF reader, dialogs, or any element by selector. Use highlightSelector to add a red border before capture.

</details> <details> <summary>UI Interaction — Click and type in the Zotero UI</summary>

Tool	Description
`zotero_click_element`	Click an element by CSS selector (toolbar/menu button, preference control, list row). Pierces shadow DOM; `index` picks among multiple matches; `mouseEvents` synthesizes a full mouse sequence.
`zotero_send_keys`	Type text into an input/textarea/contenteditable (focuses it first, fires input/change). Optional `clear` and `pressEnter`.

Resolution tries light DOM first, then pierces open shadow roots (Zotero's XUL custom elements keep internals in shadow DOM). Limitation: cannot dismiss a blocking native modal dialog (Services.prompt.confirmEx) — its nested modal loop blocks the eval thread these tools run on.

</details> <details> <summary>JavaScript Execution — Run code in Zotero context</summary>

Tool	Description
`zotero_execute_js`	Execute JavaScript in Zotero's privileged context. Auto-wraps code with top-level `return` statements in IIFE.
`zotero_inspect_object`	Explore Zotero APIs - list methods and properties of any object (e.g., `Zotero.Items`)
`zotero_open_preferences`	Open Zotero's settings window, optionally to a specific pane (built-in or plugin)
`zotero_search_prefs`	Search/discover preferences by pattern (e.g., find all prefs containing "debug")
`zotero_get_pref`	Get a preference value
`zotero_set_pref`	Set a preference value

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

Tip: Use zotero_inspect_object to explore APIs before writing code. Use zotero_search_prefs to discover preference keys.

</details> <details> <summary>Build & Scaffold — Integration with zotero-plugin-scaffold</summary>

Tool	Description
`zotero_scaffold_build`	Build plugin (dev or production mode)
`zotero_scaffold_serve`	Start dev server with hot reload
`zotero_scaffold_lint`	Run ESLint on plugin source
`zotero_scaffold_typecheck`	Run TypeScript type checking

</details> <details> <summary>Logs & Debugging — Error console and debug output</summary>

Tool	Description
`zotero_read_logs`	Read debug output (Zotero.debug)
`zotero_read_errors`	Read error console entries
`zotero_watch_logs`	Stream logs in real-time
`zotero_clear_logs`	Clear log buffer

</details> <details> <summary>Plugin Management — Install, reload, inspect</summary>

Tool	Description
`zotero_plugin_reload`	Hot reload your dev plugin
`zotero_plugin_install`	Install plugin from XPI path
`zotero_plugin_list`	List installed plugins with version/status

</details> <details> <summary>Database Access — Read-only SQLite access</summary>

Tool	Description
`zotero_db_query`	Execute SELECT query on zotero.sqlite
`zotero_db_schema`	Get table schema information
`zotero_db_stats`	Get database statistics (items, attachments, collections, size)

Note: Database access is read-only and requires Zotero to be closed, or uses a copy of the database.

</details>

🏗️ Architecture

code

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

Why this approach?

✅ Lightweight plugin — Just enables RDP, Firefox DevTools does the rest
✅ Zero-config after install — Just open Zotero normally, no special flags
✅ Rich AI context — Screenshots, DOM, and logs help the AI understand your plugin's state
✅ Hot reload — Integrates with zotero-plugin-scaffold for instant feedback
✅ Full Zotero access — Execute any Zotero API in the privileged context
✅ Cross-platform — Works on Linux, Windows, macOS

🔧 Environment Variables

Variable	Description	Default
`ZOTERO_RDP_PORT`	Remote debugging port	`6100`
`ZOTERO_RDP_HOST`	Debugging host	`127.0.0.1`
`ZOTERO_DATA_DIR`	Path to Zotero data directory	Auto-detect
`ZOTERO_PROFILE_PATH`	Path to Zotero profile	Auto-detect

📸 Screenshot Examples

typescript

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

🧑‍💻 Development

bash

# 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

<details> <summary>Project Structure</summary>

code

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/
│       │   └── index.ts          # Starts RDP server
│       ├── addon/
│       │   └── manifest.json
│       └── package.json
│
├── docs/                         # Documentation
└── package.json                  # Monorepo root

</details>

📚 Resources

Architecture & Technical Learnings — Deep dive into RDP protocol, actor hierarchy, and common pitfalls
Zotero Plugin Development — Official docs
Zotero 7 for Developers — Migration guide
zotero-plugin-scaffold — Build tooling
zotero-plugin-template — Starter template
zotero-plugin-toolkit — API helpers
Firefox RDP Protocol — Protocol docs

🤝 Contributing

Contributions are welcome! Please:

Follow existing code patterns
Add tests for new features
Update documentation
Ensure npm test and npm run lint pass

📄 License

Acknowledgments

Built for the Zotero plugin developer community
Integrates with zotero-plugin-scaffold by @windingwind
Leverages Firefox DevTools RDP for reliable communication

Install

Configuration

Environment variables

ZOTERO_RDP_PORT

RDP port for Zotero connection

ZOTERO_RDP_HOST

RDP host for Zotero connection

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-zotero-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@introfini/mcp-server-zotero-dev@1.1.2"
      ],
      "env": {
        "ZOTERO_RDP_PORT": "<YOUR_ZOTERO_RDP_PORT>",
        "ZOTERO_RDP_HOST": "<YOUR_ZOTERO_RDP_HOST>"
      }
    }
  }
}