Zotero Local MCP Bridge

---

✨ What It Does

Zotero Local MCP Bridge lets MCP-capable agents manage a local Zotero library through Zotero itself. It is not a database script that bypasses Zotero. It is a local MCP entrypoint running inside the Zotero plugin.

Area	Capability
📚 Items and collections	Read, search, create, and edit items; batch-check whether DOI records already exist; batch-manage membership in top-level collections or subcollections
📎 Attachments	Add, move, rename, and inspect attachments; import single or multiple PDF/EPUB files and call Zotero's built-in metadata recognition and attachment rename logic
📝 Annotations and citations	Read, create, and update supported PDF annotations; format citations and bibliographies through Zotero
🔁 Import and export	Import and export BibTeX, RIS, and CSL JSON
🔎 Search	Use basic search, advanced search, and saved search read/update workflows
🛡️ Safety workflow	Enforce dry-run for all writes; support approval, audit, file-level backup, and undo
🧩 Duplicates	Find duplicates and run controlled duplicate merge flows

[!NOTE] Writes do not execute immediately. The agent first receives a dry-run plan, warnings, affected targets, and confirmation data. In approval modes, execution must wait for user approval.

---

🚫 What It Does Not Do

Not supported	Reason
Managing online Zotero libraries	This project does not write through the Zotero Web API or manage remote Zotero accounts
Using ZOTERO_API_KEY	This project does not request, read, or store a Zotero API key
Writing directly to zotero.sqlite	Changes should go through Zotero internal APIs
Exposing arbitrary JavaScript eval	Ordinary management must come from the plugin command table
Managing group libraries	The current public scope covers local user libraries only
Permanent deletion or empty trash	Current delete-like flows use Zotero trash or controlled merge, not unrecoverable erase
Directly deleting existing attachment files	Attachment file operations must respect backup/undo and safety boundaries

---

📍 Scope

This plugin is designed for Zotero Desktop and a local MCP client on the same machine. The MCP endpoint is registered on Zotero's local connector server and uses local loopback access only.

Item	Current setting
Runtime location	Inside the Zotero plugin
Endpoint	http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
Library scope	Local user library
Write path	Zotero internal APIs
Network model	Local loopback, no cloud writes
Audit and backup	Must stay outside the Zotero profile, Zotero data directory, linked attachment root, and attachment directories

Run mode is configured in Settings -> Zotero Local MCP Bridge:

Mode	Behavior
readonly	Blocks all writes
askforapprove	The agent asks the user for approval after dry-run
yolo	Ordinary writes may auto-execute when the plan allows it; high-risk or future unrecoverable operations still require explicit confirmation

---

⚙️ How It Works

MCP-capable agent
  -> MCP tool call
  -> Zotero local connector server
  -> Zotero Local MCP Bridge plugin endpoint
  -> plugin command table
  -> Zotero internal API

The MCP endpoint is hosted inside the Zotero plugin:

http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp

There is no separate Node, Python, or sidecar MCP process to start. Starting Zotero starts the plugin endpoint. Closing Zotero stops it. The release build exposes MCP tools, not the old private command endpoint.

Codex and Claude Code can connect to the Streamable HTTP MCP endpoint directly. OpenCode and other clients with stdio support but no Streamable HTTP support can use the standalone stdio adapter. The adapter runs on the agent side, stays outside the XPI, and never touches the Zotero database.

---

🚀 Quick Start

1. Download Release Files

Download from GitHub Releases:

File	Purpose
zotero-local-mcp-bridge.xpi	Zotero plugin
zotero-local-mcp-bridge-<version>.mcpb	Claude Desktop MCP bundle for macOS and Windows
English skill	For English-speaking agents
Chinese skill	For Chinese-speaking agents

2. Install The Zotero Plugin

Open the Zotero plugin manager:

Tools -> Plugins

Drag zotero-local-mcp-bridge.xpi into the plugin manager window, confirm installation when prompted, and restart Zotero.

3. Choose Run Mode

Open:

Settings -> Zotero Local MCP Bridge

For first use, start with readonly or askforapprove. Use yolo only after you understand dry-run, approval, audit, and backup behavior.

4. Connect The MCP Client

Agents can connect through stdio or Streamable HTTP. Claude Desktop users on macOS or Windows can install the packaged MCPB adapter.

Option A: stdio MCP

Install the npm adapter:

npm install -g zotero-local-mcp-bridge-stdio-adapter

Then configure stdio MCP in your agent:

[mcp_servers.zotero-local-mcp-bridge]
command = "zotero-local-mcp-bridge-stdio"
args = []
startup_timeout_sec = 20
tool_timeout_sec = 120

Generic stdio MCP configuration:

{
  "mcpServers": {
    "zotero-local-mcp-bridge": {
      "type": "stdio",
      "command": "zotero-local-mcp-bridge-stdio",
      "args": []
    }
  }
}

You can also use npx without a global install:

{
  "mcpServers": {
    "zotero-local-mcp-bridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "zotero-local-mcp-bridge-stdio-adapter"]
    }
  }
}

The stdio adapter is a compatibility layer started by the agent session. It forwards stdio MCP requests to the Zotero plugin HTTP MCP endpoint. It is not the Zotero plugin itself and does not start with Zotero.

Before editing an agent configuration, verify the installed plugin and MCP endpoint:

zotero-local-mcp-bridge-stdio doctor

The one-shot command checks MCP initialization and tool discovery, then prints the detected plugin version, tool count, and ready-to-copy Codex, Claude Code, and OpenCode configurations. It does not modify agent settings.

See the client compatibility matrix for Codex, Claude Code, OpenCode, Claude Desktop, and current ChatGPT limitations.

Option B: HTTP MCP

If your agent supports Streamable HTTP / HTTP MCP, you can skip the npm package and connect directly to the Zotero plugin endpoint:

http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp

Codex example:

[mcp_servers.zotero-local-mcp-bridge]
url = "http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 120

Claude Code example:

claude mcp add --transport http zotero-local-mcp-bridge http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp

Option C: Claude Desktop MCPB

Install zotero-local-mcp-bridge-<version>.mcpb in Claude Desktop on macOS or Windows. The MCPB contains the stdio compatibility adapter, not the Zotero plugin; install the XPI first and keep Zotero open. See Claude Desktop setup.

5. Install The Matching Skill

Language	Skill
English	skills/zotero-local-mcp-bridge/SKILL.md
Chinese	skills/zotero-local-mcp-bridge-zh-cn/SKILL.md

Tell the agent to use Zotero through Zotero Local MCP Bridge. When approval is required, the agent should briefly describe the pending operation and wait for user approval.

6. Run The First Read-Only Query

Ask the agent:

List my Zotero collection tree without making changes.

The agent should call zotero_collection_get_tree with libraryScope=local-user. This query does not require write approval.

---

🧪 Examples

Ask the agent to	Expected behavior
List my Zotero collection tree	Read-only query, no write confirmation
Check which DOI values already exist in my library	Run one batch lookup and return matching items, reusable item keys, and unmatched DOI values
Add these existing items to "Current Project / Reading Queue"	Use one dry-run, one approval when required, and one batch write while skipping existing members
Create a "Reading Queue" subcollection under "Current Project"	Dry-run first, then ask for approval
Add this PDF attachment to this item	Resolve the item and file path, then dry-run the attachment operation
Import this PDF and retrieve metadata automatically	Dry-run first, then use Zotero's built-in recognition flow to create the parent item and rename the attachment according to preferences
Import these PDFs and retrieve metadata automatically	Use the batch recognition tool with one dry-run, one approval, and one execute
Export selected items as BibTeX	Read-only export, no write confirmation
Format a bibliography with a chosen style	Use Zotero's citation formatter

In approval mode, a single write operation should interact through the agent like this:

I am about to create a subcollection named "Reading Queue" under "Current Project". Approve execution?

Multiple pending operations use a numbered table, so the user can approve all operations or approve only selected numbers:

The following operations need approval:

| No. | Operation |
|---:|---|
| 1 | Move subcollection "Temporary" under "Old Project" to Zotero trash |
| 2 | Merge duplicate items "Smith 2024" and "Smith 2024 copy" |
| 3 | Add "Zotero MCP design notes" to "Current Project / Reading Queue" |

The user can reply "approve all", or reply "approve 1 and 3, reject 2".

If this project helps your workflow, consider starring the repository or opening a focused issue with reproducible feedback.

---

❤️ Support Author

---

📄 License

Zotero Local MCP Bridge is licensed under AGPL-3.0-or-later. See LICENSE.