MCP Bridge for Zotero
About
MCP server that enables AI assistants to build, test, and debug Zotero plugins via 26 tools for UI inspection, JS execution, logging, and more.
Details
- Author
- introfini
- Categories
- Developer Tools
Jump to
Setup
Install MCP Bridge for Zotero in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/introfini/mcp-server-zotero-dev
Follow the installation instructions in the repository README, then restart your MCP client.
Give your AI assistant superpowers for Zotero plugin development
Architecture·Getting Started·Available Tools
AModel Context Protocol (MCP) serverthat enables AI assistants like Claude, Cursor, and Windsurf to build, test, and debugZotero7, 8, 9, and 10 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.
- Node.js20+ and npm
- Zotero 7+— Works on all Zotero 7, 8, 9, and 10 builds (release, beta, dev)
- For plugin development:zotero-plugin-scaffold
Useinstall-mcpto add the server to your AI assistant:
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
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" } } } }
Version & updates: pin an exact version as shown above. A barenpx <pkg>(no version) keeps running whatevernpxcached and won't pick up new releases, so always include a version and-y(without-y,npxhangs waiting for an install prompt). Bump the pinned version to upgrade, or use@latestto 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 thatinstall-mcpmay write a config without-yor a version, so the manual configuration above is the most robust path.
Restart your AI assistantafter adding the configuration.
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).
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. 🎉
Screenshot Targets: Main window, preferences, PDF reader, dialogs, or any element by selector. UsehighlightSelectorto add a red border before capture.
Resolution tries light DOM first, then pierces open shadow roots (Zotero's XUL custom elements keep internals in shadow DOM).Limitation: cannot dismiss ablockingnative modal dialog (Services.prompt.confirmEx) — its nested modal loop blocks the eval thread these tools run on.
Examples:Zotero.Items.getAll(1),Zotero.Prefs.get('export.quickCopy.setting'),ZoteroPane.getSelectedItems()
Tip: Usezotero_inspect_objectto explore APIs before writing code. Usezotero_search_prefsto discover preference keys.
Note: Database access is read-only and requires Zotero to be closed, or uses a copy of the database.
┌─────────────────────────────────────────────────────────────────┐ │ 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) │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘
- ✅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
The bridge listens on port6100by default. You only need to change it if you runtwo Zotero instances at the same time(a normal profile and a development one, say), or if another process already holds 6100.
The port lives onboth sides of the bridge, and both have to agree on it.
1. Zotero side— set the plugin preference:
- Settings → Advanced → Config Editor, and accept the warning
- Search forextensions.mcp-rdp.port
- If it doesn't exist, create it: selectNumber, name itextensions.mcp-rdp.port, and enter your port
- Restart Zotero— the listener only opens at startup
Watch the type.The Config Editor pre-selectsBoolean. Creating the preference without switching toNumberstorestrueinstead of a port, and Zotero then opens the bridge on a local pipe rather than a TCP port — the debug log reports success while no MCP client can connect.
2. Client side— setZOTERO_RDP_PORTto the same value in your MCP client config:
{ "mcpServers": { "zotero-dev": { "command": "npx", "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.2"], "env": { "ZOTERO_RDP_PORT": "6101" } } } }
Change both or neither.Moving only one side disconnects the bridge: Zotero listens on one port while the client keeps dialing the other.
Launching Zotero a second time hands you the window you already have — like Firefox, it forwards to the running instance instead of starting another. A second instance needs its own profileand-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
Give that profile its ownextensions.mcp-rdp.portand the two bridges stay out of each other's way. Verified with 9.0.6 on 6100 and 10.0-beta.22 on 6101 at the same time.
Requires MCP Bridge plugin 1.0.5 or later.In 1.0.4 and earlier,extensions.mcp-rdp.portwas read under the wrong preference branch and silently ignored, so the bridge stayed on 6100 no matter what you set. If you configured a custom port against an older build, it is stored asextensions.zotero.extensions.mcp-rdp.port— that name still works, but prefer the one above.
Setextensions.mcp-rdp.enabledtofalse(Boolean) in the Config Editor and restart Zotero. The plugin stays installed but opens no listener, and no MCP client can reach Zotero until you set it back totrue.
// 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"]' });
# 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
- Architecture & Technical Learnings— Deep dive into RDP protocol, actor hierarchy, and common pitfalls
- Zotero Plugin Development— Official docs
- Zotero 10 for Developers— Migration guide for the latest major
- 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
Contributions are welcome. SeeCONTRIBUTING.mdfor setup, test conventions and the codebase-specific rules worth knowing before you start.
- Follow existing code patterns
- Add tests for new features, and skip rather than fail when Zotero is not running
- Update documentation
- There is no CI, so runnpm run build,npm run typecheck,npm run lintandnpm testyourself, and say in the PR which Zotero version you verified against
- Built for theZoteroplugin developer community
- Integrates withzotero-plugin-scaffoldby@windingwind
- Leverages Firefox DevTools RDP for reliable communication
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
AI-powered live runtime debugging with Lightrun production context.
Run, debug, and triage tests via natural language across HyperExecute, Automation, SmartUI, and Accessibility on the TestMu AI cloud.
Understand, develop, and debug authorization policies in Oso Cloud.
A comprehensive proxy that combines multiple MCP servers into a single MCP. It provides discovery and management of tools, prompts, resources, and templates across servers, plus a playground for debugging when building MCP servers.
Proxyman MCP allows AI to inspect HTTP traffic, create debugging rules, and control Proxyman - all through natural language conversations.
Debug your remote Node.js and Next.js applications directly from your AI IDE like Cursor.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Drives an Android emulator or a real device over adb: screenshots, UI hierarchy with true device-pixel coordinates, tap and type, app lifecycle, logcat, and Gradle builds and tests.
Interact with Android devices using the Android Debug Bridge (ADB).
Policy-gated MCP tools that let coding agents build, flash, stimulate and observe real embedded hardware (OpenOCD, pyOCD, STM32CubeProgrammer, serial, CAN).
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
