Zotero MCP for Claude Code

A Zotero plugin that exposes your library to AI assistants via the Model Context Protocol (MCP). This fork adds Claude Code compatibility and write operations.

Note: This fork has been developed and tested with Claude Code, Claude Desktop, and Codex on Zotero 7–10 for macOS (latest macOS). The plugin manifest declares compatibility with Zotero 7, 8, 9, and 10. It uses standard MCP over Streamable HTTP, so it should work with any MCP-compatible client and platform, but other clients and operating systems have not been tested by this fork's author.

What it does

The plugin runs an MCP server inside Zotero that AI clients connect to over HTTP. No separate server process needed.

AI Client  <--Streamable HTTP-->  Zotero Plugin (integrated MCP server)

Your AI assistant can then search your library, read PDFs, extract annotations, create items, manage collections, and more.

Quick start

1. Install the plugin

Download the latest .xpi from the Releases page and install it in Zotero via Tools > Plugins → gear menu → Install Plugin From File….

Upgrading to Zotero 10? Zotero 10 disables plugin versions older than v1.8.7 (their manifest caps compatibility at Zotero 9), which leaves nothing listening on port 23120 and MCP clients failing with ECONNREFUSED. Install v1.8.7 or later from the Releases page. Existing installs on Zotero 7–9 pick it up through auto-update.

2. Connect Claude Code

claude mcp add zotero-mcp http://127.0.0.1:23120/mcp -t http

Or add to your MCP config (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "zotero-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:23120/mcp"
    }
  }
}

If you've enabled Require auth token on local connections (or Allow remote access — which forces auth regardless), copy the token from the prefs UI and add it as a header:

{
  "mcpServers": {
    "zotero-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:23120/mcp",
      "headers": {
        "Authorization": "Bearer zmcp_<your-token>"
      }
    }
  }
}

See Authentication below.

3. Verify

claude mcp list

You should see zotero-mcp with the available tools listed.

Supported clients

The plugin preferences include a Client Configuration Generator that produces ready-to-use config for each client.

Claude Desktop setup

Claude Desktop runs local MCP servers as stdio commands, so it reaches the plugin's HTTP endpoint through the mcp-remote bridge (requires Node.js). Custom Connectors (Settings → Connectors) can't be used for this: Anthropic's cloud makes those connections, so 127.0.0.1 is unreachable.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Settings → Developer → Edit config), then quit and reopen Claude Desktop:

{
  "mcpServers": {
    "zotero-mcp": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:23120/mcp"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}

Use full paths: Claude Desktop launched from the Dock doesn't load your shell profile, so npx from nvm or other shell-managed installs isn't on its PATH. Point command at your npx (which npx) and include the directory containing node in env.PATH. With auth enabled, add "--header", "Authorization: Bearer zmcp_<your-token>" to args. Settings → Developer shows the server as Running; logs are in ~/Library/Logs/Claude/mcp-server-zotero-mcp.log.

MCP tools (50 max total)

Read tools (26 — always available)

Write tools (24 — when enabled in preferences)

Write tools are gated by per-scope opt-in checkboxes in preferences (see Write scopes below). Tools whose scopes are disabled are hidden from the tools/list response — they don't just fail-on-call, they don't exist as far as the client can see.

Undo (Zotero 10): changes made through write tools land on Zotero's undo stack, so Edit → Undo (Cmd/Ctrl+Z in the items list) reverts them like Zotero's own edits — labelled "Undo Add Tag", "Undo Edit Metadata", and so on. A batch tool is one undo step. Trashing and restoring are undoable; creating items and permanently deleting are not (a Zotero limitation). The undo history lives in memory and clears when Zotero restarts. On Zotero 7–9 there is no undo.

Authentication

The plugin auto-generates a per-install bearer token on first start, stored in the extensions.zotero.zotero-mcp-plugin.mcp.server.authToken preference and surfaced in Settings → Zotero MCP for Claude Code → MCP Server → Authentication with Copy and Regenerate buttons.

When auth is required, send the token via either:

Authorization: Bearer zmcp_<48-hex-chars>

or

X-Zotero-MCP-Token: zmcp_<48-hex-chars>

X-Zotero-MCP-Token exists for browser-extension callers that can't set Authorization. Both headers force a CORS preflight, defeating drive-by simple-form CSRF.

Loopback default (no auth) keeps existing client configs working out of the box. Public-facing or shared-machine setups should enable requireAuth. The /ping, /capabilities, /help, /mcp/status, and GET /mcp endpoints stay open even when auth is on, so health checks and config generators don't need credentials.

Regenerating the token invalidates every existing client config — clients will get 401 until you update them.

Defense-in-depth checks (always on)

These run regardless of auth state:

• Origin: null (sandboxed iframes, file://, cross-origin redirects) is rejected
• POST /mcp requires Content-Type: application/json (defeats text/plain CSRF via simple form POST)
• Host header must be loopback when allowRemote=false
• Duplicate Host headers rejected
• Mcp-Session-Id validated against ^mcp-[a-f0-9-]{8,80}$ and capped at 256 active sessions with LRU eviction
• Global + per-client token-bucket rate limits, with a stricter bucket on write tools. Remote clients are limited per IP; loopback clients are limited per active Mcp-Session-Id (falling back to the address), so Claude Code, its subagents and Claude Desktop don't share one bucket. initialize, notifications/*, tools/list and ping get a small reserve so a client can still reconnect after a burst of tool calls
• 10s wall-clock deadline on full request body read
• Content-Length > 1MB rejected before reading
• Zotero 9/10-compatible socket reads use Gecko readiness callbacks rather than available() polling, avoiding accepted-but-unresponsive MCP connections

Write scopes

mcp.write.enabled (single boolean) was replaced in v1.8.0 by seven granular scopes. A tool is only exposed in tools/list when every scope it requires is enabled.

Scopes marked ⚠ are destructive and default to off. Multi-scope tools require all listed scopes:

Migration from mcp.write.enabled

On first run after upgrading from v1.7.0 or earlier:

• If the legacy mcp.write.enabled was true, the safe scopes (notes, tags, collections, metadata) migrate on; the destructive scopes (delete, bulk, import) stay off. Re-enable them deliberately if you need them.
• If mcp.write.enabled was unset or false, all scopes default to off.

Reading scope state programmatically

Zotero.Prefs.get("extensions.zotero.zotero-mcp-plugin.mcp.write.metadata", true)
// → true | false | undefined

The same pref keys appear in ~/Library/Application Support/Zotero/Profiles/<profile>/prefs.js.

Plugin preferences

Configure in Zotero > Settings > Zotero MCP for Claude Code:

• MCP Server -- Enable/disable, port (default 23120), remote access
• Authentication -- Bearer token (Copy / Regenerate), require-auth-on-loopback toggle
• Write Scopes -- Per-scope opt-in (notes, tags, collections, metadata, delete, bulk, import)
• Client Configuration Generator -- Generate config JSON for any supported AI client
• MCP Content Settings -- Content processing mode (minimal/preview/standard/complete/custom), max tokens
• Semantic Search -- Embedding provider (OpenAI, Ollama, etc.), model, dimensions, API key
• Semantic Index -- Build/rebuild/clear index, auto-update, progress monitoring

Semantic search

The plugin supports AI-powered semantic search using embedding vectors:

1. Configure an embedding provider in preferences (OpenAI, Ollama, or any OpenAI-compatible API)
2. Build the index (indexes item titles, abstracts, and full text)
3. Use semantic_search for natural language queries or find_similar to find related items

The vector index is stored locally in SQLite with Int8 quantization for efficient storage.

Development

Prerequisites

• Zotero 7, 8, 9, or 10
• Node.js 22.8+ (required by zotero-plugin-scaffold 0.9)

Setup

cd zotero-mcp-plugin
npm install
npm run build    # Production build
npm run start    # Dev mode with auto-reload

Testing

npm run check        # lint + build/type check + unit tests (the local gate)
npm run test:unit    # Mocha unit tests in Node (no Zotero needed)
npm run lint:check   # Prettier + ESLint

Endpoints

Protocol versions supported: 2024-11-05 and 2025-03-26 (negotiated via initialize).

Fork changes

This fork (lricher7329/zotero-mcp-claude-code) adds the following on top of the upstream cookjohn/zotero-mcp:

• Claude Code compatibility -- Proper request body reading, Accept header validation, DELETE method, notification handling, batch requests, dual protocol version support (2024-11-05 + 2025-03-26)
• Write operations -- ~24 MCP write tools for creating/updating items, notes, tags, collections, relations, and attachments, plus batch operations and trash management — all gated by per-scope opt-ins
• Library introspection -- Schema discovery tools (item types, creator types, field lists), library stats, trash listing, recently modified items
• Security hardening (v1.8.0) -- Per-install bearer token auth; Origin/Content-Type CSRF protection; per-scope write opt-ins (destructive ops default off); global + per-IP + per-session rate limits; SSRF guard with IPv6-mapped-IPv4 and decimal/octal IPv4 detection; itemKey/collectionKey format validation; session ID hardening with LRU cap; body-read deadline; sanitized error messages
• MCP/JSON-RPC compliance fixes (v1.8.0) -- Tool execution failures returned as result.isError (LLM can recover) rather than -32603; argument validation maps to -32602; parse-error id: null per spec; notifications/initialized correct; empty batch returns -32600; dropped false tools.listChanged advertisement
• get_item_details mode=complete -- Now enumerates all item-type fields via Zotero.ItemFields.getItemTypeFields, including extra (PMID/PMCID/citation key per Zotero convention), collections membership, dateAdded/dateModified/accessDate. Critical for downstream identifier extraction.
• Per-session rate limits on loopback (v1.8.10) -- Every local client shared one 127.0.0.1 bucket, so parallel Claude Code subagents could exhaust it and reconnects failed with "Rate limit exceeded". Loopback traffic is now limited per active session, reconnect handshakes draw on a small reserve, and the global cap burst rose from 120 to 240
• Zotero 10 native features (v1.8.9) -- MCP edits (metadata, notes, tags, collections, related items, restore) can be undone in Zotero with Cmd/Ctrl+Z, one undo step per call or batch; full text reads Zotero's cached index again (Zotero 10 removed the old API, so PDF text timed out) and search_fulltext uses Zotero's search index; get_content on long papers drops from minutes to about a second; search_library accepts structured condition groups and resultLevel
• Zotero 10 support (v1.8.7) -- Manifest and auto-update strict_max_version raised to 10.*; attachment file-size lookup moved from the legacy OS.File API to IOUtils
• Codebase audit -- Typed errors, API validation, singleton fixes, batched queries, module refactoring, and a Node unit-test suite (npm run test:unit)

License

MIT

Acknowledgements

• Zotero -- Open-source reference management
• cookjohn/zotero-mcp -- Original upstream project
• Model Context Protocol -- The protocol standard
• Zotero Plugin Template -- Plugin scaffolding