zotero-mcp

A Model Context Protocol server for Zotero. It lets Claude Code, Claude Desktop and any other MCP client search your library, read items, take notes, file things into collections and find papers by meaning rather than by exact words.

This is a ground-up rewrite of the earlier zotero-mcp server with a small, typed tool surface, bounded responses, real error reporting and a semantic search index that is chunk-level, incremental and reranked.

What it does

Read

Find by meaning

Write (only when a web API key with write permission is configured)

Every write tool defaults to dry_run=true and returns a preview of the change. The client must pass dry_run=false to apply it. Updates carry Zotero's version header, so a concurrent edit in the desktop app produces a clear conflict error rather than a silent overwrite.

Install

Requires Python 3.10+ and uv.

uv tool install 'zotero-mcp-next[semantic,pdf] @ git+https://github.com/v-i-n-a-y/zotero-mcp-v2'

The semantic extra pulls in ChromaDB and sentence-transformers for semantic search; pdf adds PyMuPDF and ebooklib for fulltext extraction. Omit both for a lean install with keyword search only.

Configure

The server reads environment variables (or a JSON file via ZOTERO_MCP_CONFIG).

Modes. local talks to the running Zotero desktop app (port 23119): fast, no key needed, read-only. web talks to api.zotero.org and needs a key. hybrid reads locally and writes through the web API, which is the best everyday setting when the desktop app is open. auto picks local if the app is reachable, otherwise web.

Claude Code

claude mcp add zotero -s user \
  -e ZOTERO_MCP_MODE=hybrid \
  -e ZOTERO_API_KEY=... \
  -e ZOTERO_LIBRARY_ID=... \
  -- zotero-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_MCP_MODE": "hybrid",
        "ZOTERO_API_KEY": "...",
        "ZOTERO_LIBRARY_ID": "..."
      }
    }
  }
}

Semantic search

Build the index once from a terminal; it needs the desktop app open (or web mode) to read fulltext:

zotero-mcp index build     # first run: roughly an hour per thousand PDFs
zotero-mcp index status

After that the running server refreshes the index on the schedule above, re-embedding only items whose Zotero version changed. Extracted fulltext is cached beside the index, so switching embedding models rebuilds in minutes.

How a query is answered: the vector index returns a pool of candidate chunks (metadata chunk plus fulltext chunks per item, with trailing reference lists stripped), a cross-encoder rescores the pool against the query, citation-dense chunks are penalised, and chunks collapse to one hit per item with a small bonus for items that matched in several places. Everything runs locally; on Apple silicon the models use Metal.

CLI

zotero-mcp                 # serve over stdio (what MCP clients run)
zotero-mcp health          # can the configured library be reached?
zotero-mcp index build     # build or incrementally refresh the semantic index
zotero-mcp index status
zotero-mcp index clear
zotero-mcp version

Design

• Every response is bounded. Lists are paged with opaque cursors; long text is truncated with an explicit marker.

• Failures raise MCP tool errors with a stable code (not_found, invalid_input, auth, write_conflict, backend_unavailable, unsupported) and a hint, never a success whose text starts with "Error:".

• Tools return both markdown for humans and structured content for clients that can use it.

• Logging goes to stderr; stdout carries only the protocol.

More in docs/design.md.

Development

uv sync --extra dev
uv run pytest
uv run ruff check src tests

Licence

MIT.