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 on Zotero 7–9 for macOS (latest macOS). The plugin manifest declares compatibility with Zotero 7, 8, and 9. 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    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 > Add-ons.

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_"
      }
    }
  }
}

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.

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.

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_

or

X-Zotero-MCP-Token: zmcp_

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-IP + per-session token-bucket rate limits, with a stricter bucket on write tools
• 10s wall-clock deadline on full request body read
• Content-Length > 1MB rejected before reading
• Zotero 9-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//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, or 9
• Node.js 18+

Setup

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

Testing

npm run test:unit    # 37 unit tests (mathUtils, textChunker)
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.
• Codebase audit – Typed errors, API validation, singleton fixes, batched queries, module refactoring, 37 unit tests

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