mcp-zotero

MCP server for Zotero — 38 library tools + optional semantic search via local embeddings.

Install

Base (Zotero API tools only)

uv tool install mcp-zotero

With semantic search

uv tool install "mcp-zotero[rag]"

Adds 8 RAG tools for indexing PDFs and searching by meaning. Downloads a ~80MB embedding model on first use.

With OCR for scanned PDFs

uv tool install "mcp-zotero[rag,ocr]"

Adds docling-based OCR fallback for PDFs that contain scanned images instead of text.

Configuration

Add to your Claude Code MCP settings (.mcp.json or ~/.claude/settings.json):

{
  "mcpServers": {
    "zotero": {
      "command": "mcp-zotero",
      "env": {
        "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID",
        "ZOTERO_LOCAL": "true",
        "ZOTERO_LOCAL_KEY": "YOUR_LOCAL_KEY",
        "ZOTERO_API_KEY": "YOUR_API_KEY",
        "ZOTERO_ATTACHMENTS_DIR": "~/Zotero/storage"
      }
    }
  }
}

Environment variables

RAG-only variables (when installed with [rag])

Tools

Base tools (38)

Always available. Covers the full Zotero API:

Search & browse: search_items, top_items, get_item, trash_items, deleted_items

Collections: list_collections, list_collections_top, list_collections_sub, get_collection, collection_items, collection_items_top, collection_tags, create_collections, update_collection, delete_collection, add_item_to_collection, remove_item_from_collection

Tags: list_tags, item_tags, delete_tags

Items: add_item, update_item, delete_item

Attachments: download_attachments, attach_file, attach_linked_file

Schema: item_types, item_fields, item_type_fields, creator_fields, item_creator_types, item_attachment_link_modes

Saved searches: list_searches, list_groups, create_saved_search, delete_saved_search

System: ping, health_check

RAG tools (8)

Available when installed with [rag]. Semantic search across your PDF library:

Development

git clone https://github.com/nealcaren/mcp-zotero.git
cd mcp-zotero
uv venv && uv pip install -e ".[dev,rag]"
pytest

License

MIT