DeepZotero

Semantic search over a Zotero library. PDFs are extracted (text, tables, figures), chunked, embedded, and stored in ChromaDB. An MCP server exposes the index to Claude Code (or any MCP client) as 13 tools for semantic search, boolean search, table/figure search, context expansion, citation graph lookup, indexing, and cost tracking.

What it extracts

• Text — section-aware chunks with overlap, classified by document section (abstract, methods, results, etc.)

• Tables — vision-based extraction via Claude Haiku 4.5. Each table is rendered to PNG and transcribed to structured markdown (headers, rows, footnotes). Falls back to PyMuPDF heuristics if vision is disabled.

• Figures — detected with captions, extracted as PNGs, searchable by caption text.

Related MCP server: scientific-papers-mcp

Requirements

• Python 3.10+

• A Gemini API key for embeddings (unless using embedding_provider: "local")

• An Anthropic API key for vision-based table extraction (optional but recommended)

• A Zotero installation with PDFs in storage/

• Tesseract-OCR — only needed to OCR scanned / image-only PDF pages. Install Tesseract with the language data you need, then set the TESSDATA_PREFIX environment variable to its tessdata directory (e.g. C:\Program Files\Tesseract-OCR\tessdata). PyMuPDF locates the OCR data via that variable; without it, scanned pages are skipped ("OCR disabled because Tesseract language data not found."). Text-based PDFs do not need Tesseract.

Install

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

For vision table extraction:

.venv/Scripts/python.exe -m pip install -e ".[vision]"

Setup

1. Configuration

cp config.example.json config.json

Edit config.json (lives in the repo root, next to config.example.json; gitignored so your keys are never committed):

{
    "zotero_data_dir": "~/Zotero",
    "chroma_db_path": "~/.local/share/deep-zotero/chroma",
    "gemini_api_key": "YOUR_GEMINI_KEY",
    "anthropic_api_key": "YOUR_ANTHROPIC_KEY"
}

All other fields have sensible defaults. You can also set GEMINI_API_KEY and ANTHROPIC_API_KEY as environment variables instead. To load the config from a different location, point the DEEP_ZOTERO_CONFIG environment variable at it, or pass --config PATH to the CLI.

2. API keys

Gemini (required for default embeddings): Get a key at aistudio.google.com/app/apikey. Set it as gemini_api_key in config or GEMINI_API_KEY env var. If you don't want to use Gemini, set "embedding_provider": "local" to use ChromaDB's built-in all-MiniLM-L6-v2 model (no API key needed, lower quality).

Anthropic (required for vision table extraction): Get a key at console.anthropic.com. Set it as anthropic_api_key in config or ANTHROPIC_API_KEY env var. Without this key, tables are still extracted via PyMuPDF heuristics but accuracy on complex tables is lower. Vision extraction uses the Anthropic Batch API with Claude Haiku 4.5 — cost is roughly $0.016 per table, with prompt caching reducing cost on large batches.

To disable vision extraction entirely:

{
    "vision_enabled": false
}

3. Index your library

deep-zotero-index -v

To test with a subset first:

deep-zotero-index --limit 10 -v

This reads the Zotero SQLite database (read-only, safe while Zotero is open), extracts text/tables/figures from each PDF, chunks the text, embeds via Gemini, and stores everything in ChromaDB.

CLI options:

The indexer is incremental — it only processes items not already in the index. Use --force after changing chunk_size, embedding_dimensions, or ocr_language.

You can also trigger indexing from the MCP client via the index_library tool.

4. Register the MCP server

The repo ships .mcp.json.example as a template (the real .mcp.json is gitignored because the interpreter path is machine-specific). Copy it and set the command to your venv's Python:

cp .mcp.json.example .mcp.json

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

On macOS/Linux the interpreter is /path/to/zotero_citation_mcp/.venv/bin/python. Claude Code auto-loads a project-scoped .mcp.json from the repo root; alternatively, put the same mcpServers block in ~/.claude/settings.json.

If you need scanned-page OCR, make sure TESSDATA_PREFIX (see Requirements) is set in the environment the server runs in.

Restart Claude Code. All 13 tools will be available.

Configuration reference

Zotero

Embedding

Chunking

Vision

Reranking

OCR

OpenAlex

MCP tools

Semantic search

search_papers — Passage-level semantic search. Returns matching text with surrounding context, reranked by composite score (similarity × section weight × journal weight). Supports required_terms for combining semantic search with exact word matching — each term must appear as a whole word in the passage.

Parameters: query, top_k (1-50), context_chunks (0-3), year_min, year_max, author, tag, collection, chunk_types (text/figure/table), section_weights, journal_weights, required_terms (list of words that must appear in passage).

search_topic — Paper-level topic search, deduplicated by document. Groups chunks by paper, scores by average and best composite relevance.

Parameters: query, num_papers (1-50), year_min, year_max, author, tag, collection, chunk_types, section_weights, journal_weights.

search_tables — Semantic search over table content (headers, cells, captions). Returns tables as markdown.

Parameters: query, top_k (1-30), year_min, year_max, author, tag, collection, journal_weights.

search_figures — Semantic search over figure captions. Returns figure metadata and paths to extracted PNGs.

Parameters: query, top_k (1-30), year_min, year_max, author, tag, collection.

Boolean search

search_boolean — Exact word matching via Zotero's native full-text index. Returns papers (not passages) matching AND/OR word queries. No phrase search, no stemming.

Parameters: query (space-separated terms), operator (AND/OR), year_min, year_max.

Context expansion

get_passage_context — Expand context around a passage from search_papers. For table results, pass table_page and table_index to find body text citing the table.

Parameters: doc_id, chunk_index, window (1-5), table_page, table_index.

Citation graph (OpenAlex)

Requires the document to have a DOI in Zotero.

find_citing_papers — Papers that cite a given document. Parameters: doc_id, limit (1-100).

find_references — Papers a document cites. Parameters: doc_id, limit (1-100).

get_citation_count — Citation and reference counts. Parameters: doc_id.

Index management

index_library — Trigger indexing from the MCP client. Parameters: force_reindex, limit, item_key, title_pattern, no_vision.

get_index_stats — Document/chunk/table/figure counts, section coverage, journal coverage.

get_reranking_config — Current reranking weights and valid override values.

get_vision_costs — Vision API batch usage and cost summary. Parameters: last_n (recent entries to show).

Reranking

Search results are scored:

composite_score = similarity^alpha * section_weight * journal_weight

Default section weights:

Default journal weights: Q1=1.0, Q2=0.85, Q3=0.65, Q4=0.45.

Override per-call via section_weights and journal_weights parameters. Set a section to 0 to exclude it. Disable reranking entirely with "rerank_enabled": false.

Shared filter parameters

Debug viewer

tools/debug_viewer.py is a PyQt6 browser for inspecting the ChromaDB index — view papers, tables (rendered markdown vs PDF), figures, and individual chunks.

.venv/Scripts/python.exe tools/debug_viewer.py