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.

> [!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

📍 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.

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

⚙️ 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:

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

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

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.