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

🚀 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:

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

Add to your MCP client config:

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

Restart your AI assistant after adding the configuration.

2. Install MCP Bridge Plugin in Zotero

Download zotero-mcp-bridge.xpi and install:

1. In Zotero: Tools → Plugins
2. Click ⚙️ → Install Plugin From File
3. Select the downloaded .xpi file
4. 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 (26 total)

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

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.

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

🏗️ Architecture

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

📸 Screenshot Examples

// 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

# 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 -w mcp-server
npm run build -w zotero-plugin-mcp-rdp

# Run tests
npm test

# Development mode (watch)
npm run dev -w mcp-server

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

📚 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:

1. Follow existing code patterns
2. Add tests for new features
3. Update documentation
4. Ensure npm test and npm run lint pass

📄 License

MIT © introfini

Acknowledgments

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