Zotero Chunk RAG

You can run a Zotero-based passage retrieval MCP server that indexes PDFs from your Zotero library, embeds passages with Gemini, stores them in a vector index, and exposes targeted passages with surrounding context to MCP clients like Claude Code.

How to use

You will run the MCP server locally and connect an MCP client to it. The server provides four tools for your client to call: search_papers to retrieve relevant passages across papers, search_topic to find papers related to a topic, get_passage_context to expand the surrounding text for a chosen passage, and get_index_stats to check the indexing state. Use these tools in your MCP client to perform literature search, obtain precise quotations, and read contextual passages.

How to install

Prerequisites: Python 3.10 or newer must be installed on your system.

Create a Python virtual environment and install the package in editable mode.

python -m venv .venv
.venv/Scripts/python.exe -m pip install -e .

Configuration and running the server

Configure your Gemini API key and the paths used by the server. You can place configuration in ~/.config/zotero-chunk-rag/config.json or set GEMINI_API_KEY in your environment.

Example configuration values you may use in config.json (keys and descriptions are shown here directly):

{
  "zotero_data_dir": "~/Zotero",
  "chroma_db_path": "~/.local/share/zotero-chunk-rag/chroma",
  "embedding_model": "gemini-embedding-001",
  "embedding_dimensions": 768,
  "chunk_size": 400,
  "chunk_overlap": 100,
  "gemini_api_key": "YOUR_KEY_HERE"
}

Register the MCP server for your MCP client

Register a local MCP server that your MCP client can call. The standard approach is to run the Python module as a local process and expose it under a known command.

Use the following configuration to register the MCP server with your MCP client. This example runs from a Windows-style path to a Python virtual environment and uses the server entry point zotero_chunk_rag.server.

{
  "mcpServers": {
    "zotero_chunk_rag": {
      "command": "C:\\path\\to\\zotero_citation_mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "zotero_chunk_rag.server"]
    }
  }
}

Using Gemini API key securely

The Gemini API key is required to generate embeddings for your PDFs. Store the key securely and ensure it is accessible to the server either by including gemini_api_key in the config.json or by exporting GEMINI_API_KEY in your environment.

export GEMINI_API_KEY=YOUR_KEY_HERE

Indexing your Zotero library

Index the full Zotero library so your MCP client can search across all PDFs. The process reads Zotero’s SQLite database, extracts text from PDFs, chunks the text, embeds, and stores the results in the vector index.

python scripts/index_library.py -v

Initial indexing tests

To test with a small subset before indexing the entire library, limit the indexing run to a small number of items.

python scripts/index_library.py --limit 10 -v

Available tools

search_topic

Find the most relevant papers for a topic, deduplicated by paper. Returns paper metadata and the best passage scores, including the strongest passage context.

search_papers

Perform passage-level semantic search across indexed chunks. Returns matched passages with scores, metadata, and optional surrounding context chunks.

get_passage_context

Expand the context window around a specific passage to read more surrounding text, returning the requested chunks with page numbers and a merged text field.

get_index_stats

Return the current state of the index, including total documents, total chunks, and average chunks per document.