zotero_clear_logs
Clear the debug log buffer and error console.
LABSCO SUMMARY
Closes the loop that makes Zotero plugin work slow: the assistant can see the UI, run code inside it, and read the error it caused.
Screenshots plus the DOM tree plus the error console mean a broken panel can be diagnosed without you narrating it, and executing JavaScript in Zotero's own context turns "what does this API return" into a call rather than a guess. Two instances at once is a supported setup — give each profile its own bridge port — which is how you compare behaviour across Zotero versions.
What it is
A development server for Zotero 7 and later. A small bridge plugin opens Zotero's remote debugging port, and these tools drive the running application through it.
What you get
- JavaScript executed inside Zotero's privileged context, with full access to the Zotero APIs, plus object inspection to discover what an API actually exposes
- UI inspection: screenshots of the window or one element by CSS selector, a simplified DOM tree, element details, and computed styles
- UI interaction that is shadow-DOM aware — click a toolbar button, menu item or list row, and type into an input or contenteditable
- Debug output and the error console read back with stack traces and source locations, cleared on demand, or watched so new messages are collected while you work
- Preferences read, set and searched, so you can find the key before changing it, and the preferences window opened at a specific pane
- Build integration with zotero-plugin-scaffold: build, run the dev server with hot reload, lint, and typecheck the plugin project
- Plugin management — list what is installed with versions and status, install from a local XPI, and reload the one you are working on
- Read-only SQL against zotero.sqlite for debugging, with schema and statistics alongside it
- Window listing, so tools can be aimed at a specific Zotero window
Requirements
Zotero 7 or later running locally, with the MCP Bridge plugin installed to open the remote debugging port — 6100 by default, set on both sides through the extensions.mcp-rdp.port preference if you change it, and note that Zotero's Config Editor defaults to Boolean when creating it, which silently produces a pipe instead of a TCP port. Node.js 20+ and npm; installed from npm as @introfini/mcp-server-zotero-dev, and install-mcp wires it into most clients. zotero-plugin-scaffold is needed for the build tools. Setting extensions.mcp-rdp.enabled to false closes the bridge without uninstalling anything.
Setup effort
Follow the published steps
USE CASES
01
Finding out why your panel renders wrong
Screenshot the element, inspect it in the DOM, and read its computed styles.
02
Chasing an error you cannot reproduce by clicking
Start watching the logs, drive the UI, then read the errors with their stack traces.
03
Learning an API before you write against it
Inspect the object to see its methods and properties, then try the call in Zotero's own context.
04
Iterating on the plugin quickly
Run the scaffold dev server for hot reload, typecheck and lint, then reload the plugin in place.
05
Checking what your plugin wrote to the library
Read zotero.sqlite with a SELECT, using the schema tool to find the tables first.
06
Testing behaviour under a specific setting
Search for the preference key, read its current value, set it, and confirm the bridge is still up.
28 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
zotero_click_element
Click an element in a Zotero window by CSS selector (toolbar/menu button, preference control, list row, etc.). Resolves light DOM first, then pierces open shadow roots (Zotero's XUL custom elements keep internals in shadow DOM). If the selector matches several elements, use index to pick one. By default calls element.click() (which fires the XUL command for buttons/menuitems); set mouseEvents=true to dispatch a synthesized mousedown/mouseup/click sequence for content that needs real mouse events. Cannot dismiss a BLOCKING native modal dialog (Services.prompt.confirmEx) — see the module note.
zotero_db_query
Execute a SELECT query on Zotero's database. Only SELECT queries are allowed for safety. Note: Database may be locked if Zotero is running - a copy may be used.
zotero_db_schema
Get database schema information. If table is specified, returns columns for that table. Otherwise returns list of all tables.
zotero_db_stats
Get database statistics: item counts, file size, etc.
zotero_execute_js
Execute JavaScript code in Zotero's privileged chrome context. Has full access to Zotero APIs (Zotero.*, ZoteroPane, etc.). Use for testing code snippets, inspecting state, or performing actions. Prefer a dedicated tool when one fits the question (zotero_db_query for library data, zotero_read_logs/zotero_read_errors for output, zotero_inspect_object for API discovery); reach for raw JS only when none does. Code with top-level 'return' statements is auto-wrapped in an IIFE. Tip: For complex objects, use JSON.stringify(obj) to get full data. IMPORTANT: Before calling unknown APIs, use zotero_inspect_object to discover available methods - don't guess API names.
zotero_get_dom_tree
Get a simplified DOM tree structure. Shows tag names, IDs, classes, and child counts for navigation.
zotero_get_pref
Get a Zotero preference value. Common prefs: extensions.zotero.*, general.*, export.*
zotero_get_styles
Get computed CSS styles for an element. Useful for debugging layout and styling issues.
zotero_inspect_element
Find DOM elements by CSS selector and return their details. Returns: tagName, id, className, attributes, text content, bounding rect, child count.
zotero_inspect_object
Inspect a Zotero/JavaScript object to discover its methods and properties. Use to explore APIs like Zotero.Items, ZoteroPane, Zotero.Prefs without manual JS execution. Returns methods with signatures and properties with their types/values.
zotero_list_windows
List all open Zotero windows with their IDs, types, and titles. Use the windowId in other tools to target specific windows.
zotero_open_preferences
Open Zotero's preferences/settings window. Optionally navigate directly to a specific pane. For built-in panes, use: 'general', 'sync', 'export', 'cite', 'advanced'. For plugin panes, use the plugin ID (e.g., 'zotseek@zotero.org' or just 'zotseek').
zotero_ping
Test connection to Zotero and get version info. Use this to verify that Zotero is running and the MCP Bridge for Zotero plugin is active.
zotero_plugin_install
Install a Zotero plugin from a local XPI file. The plugin will be installed and Zotero may need to be restarted.
zotero_plugin_list
List all installed Zotero plugins/add-ons with their IDs, names, versions, and status.
zotero_plugin_reload
Reload a Zotero plugin. If a plugin ID is provided, reloads that specific plugin. Otherwise attempts to reload based on the current project.
zotero_read_errors
Read errors from Zotero's error console. Returns JavaScript errors with stack traces and source locations.
zotero_read_logs
Read Zotero's debug log output. Shows recent debug messages from Zotero.debug() calls.
zotero_scaffold_build
Build a Zotero plugin project using zotero-plugin-scaffold. Runs 'npm run build' or 'npm run build:dev' in the project directory.
zotero_scaffold_lint
Run ESLint on a Zotero plugin project.
zotero_scaffold_serve
Start/stop the zotero-plugin-scaffold dev server with hot reload. This watches for changes and automatically rebuilds/reloads the plugin.
zotero_scaffold_typecheck
Run TypeScript type checking on a Zotero plugin project.
zotero_screenshot
Capture a screenshot of Zotero. Can capture the main window, a specific window, or a specific element by CSS selector. Optionally highlight an element with a red border.
zotero_search_prefs
Search and list Zotero/Firefox preferences. Use to discover available preference keys before using zotero_get_pref/zotero_set_pref. Can filter by branch prefix (e.g., 'extensions.zotero.') and/or substring pattern.
zotero_send_keys
Type text into an element in a Zotero window (an input/textarea or any contenteditable). If a selector is given the element is focused first (light DOM, then open shadow roots); otherwise the window's active element is used. Fires input/change events so listeners react. Optionally clear first and/or press Enter afterwards. Note: a few widgets (e.g. Zotero's quick-search) only fully react to their own command handler, not a raw input event — prefer a direct field where possible.
zotero_set_pref
Set a Zotero preference value. Use with caution - some preferences require restart.
zotero_watch_logs
Start/stop watching for new log messages. Use action='start' to begin collecting, 'get' to retrieve collected logs, 'stop' to end.
BEFORE YOU INSTALL
What to know first
Tools you get
28 tools when we connected. zotero_ping, which tests the connection to Zotero and returns its version, is missing from the documentation's tables even though their heading says 28.
Requires
- Node.js 20+ and npm
- Zotero 7+ — Works on all Zotero 7, 8, 9, and 10 builds (release, beta, dev)
- For plugin development: zotero-plugin-scaffold
- The MCP Bridge plugin (zotero-mcp-bridge.xpi) installed in Zotero — steps under Installation
CONTEXT COST
Light Standing cost
Rated by the size of the 28 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Setup
Install the MCP Bridge plugin in Zotero (once): download zotero-mcp-bridge.xpi from https://github.com/introfini/mcp-server-zotero-dev/releases/latest
In Zotero open Tools → Plugins, click the gear icon → Install Plugin From File, and select the downloaded .xpi file
Restart Zotero — the plugin opens the debugging port (6100) the server connects to
npx
TERMINAL
npx -y @introfini/mcp-server-zotero-dev@1.1.1MCP Clients
Claude Code
CLAUDE CODE · TERMINAL
npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-codeCursor
CURSOR · TERMINAL
npx -y install-mcp @introfini/mcp-server-zotero-dev --client cursorGitHub Copilot in VS Code
GITHUB COPILOT IN VS CODE · TERMINAL
npx -y install-mcp @introfini/mcp-server-zotero-dev --client vscodeWindsurf
WINDSURF · TERMINAL
npx -y install-mcp @introfini/mcp-server-zotero-dev --client windsurfAny MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"zotero-dev": {
"command": "npx",
"args": [
"-y",
"@introfini/mcp-server-zotero-dev@1.1.1"
],
"env": {
"ZOTERO_RDP_PORT": "6100"
}
}
}
}
