home / mcp / zotero chunk rag mcp server
Exposes Zotero passage chunks via MCP for precise retrieval with context using Gemini embeddings.
Configuration
View docs{
"mcpServers": {
"ccam80-zotero-chunk-mcp": {
"command": "C:\\\\path\\\\to\\\\zotero_citation_mcp\\\\.venv\\\\Scripts\\\\python.exe",
"args": [
"-m",
"zotero_chunk_rag.server"
],
"env": {
"GEMINI_API_KEY": "YOUR_KEY_HERE"
}
}
}
}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.
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.
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 .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 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"]
}
}
}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_HEREIndex 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 -vTo 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 -vFind the most relevant papers for a topic, deduplicated by paper. Returns paper metadata and the best passage scores, including the strongest passage context.
Perform passage-level semantic search across indexed chunks. Returns matched passages with scores, metadata, and optional surrounding context chunks.
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.
Return the current state of the index, including total documents, total chunks, and average chunks per document.