Zotero Chunk MCP

DeepZotero

Zotero库的语义搜索。PDF被提取（文本、表格、图形）、分块、嵌入并存储在ChromaDB中。MCP服务器将索引作为13种工具公开给Claude Code（或任何MCP客户端），用于语义搜索、布尔搜索、表/图搜索、上下文扩展、引文图查找、索引和成本跟踪。

它提取了什么

• 文本 --具有重叠的节感知块，按文档节（摘要、方法、结果等）分类
• 表格 --通过Claude Haiku 4.5进行基于视觉的提取。每个表格都呈现为PNG格式，并转录为结构化的markdown（标题、行、脚注）。如果视力受损，则返回PyMuPDF启发式算法。
• 图 --通过字幕检测，提取为PNG，可通过字幕文本搜索。

需求

• Python 3.10+
• A. Gemini API密钥 用于嵌入（除非使用 embedding_provider: "local")
• 一 无烟煤API键 用于基于视觉的表格提取（可选但推荐）
• 带PDF的Zotero安装 storage/

安装

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

对于视觉表提取：

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

设置

1.配置

mkdir -p ~/.config/deep-zotero
cp config.example.json ~/.config/deep-zotero/config.json

编辑 ~/.config/deep-zotero/config.json:

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

所有其他字段都有合理的默认值。您还可以设置 GEMINI_API_KEY 和 ANTHROPIC_API_KEY 作为环境变量。

2.API密钥

Gemini（默认嵌入所需）： 获取钥匙 Aistudio.google.com/app/apikey.将其设置为 gemini_api_key 在配置或 GEMINI_API_KEY env var.如果你不想使用Gemini，设置 "embedding_provider": "local" 使用ChromaDB内置的全MiniLM-L6-v2型号（无需API密钥，质量较低）。

拟人（提取视觉表时需要）： 获取钥匙 console.anthropic.com.将其设置为 anthropic_api_key 在配置或 ANTHROPIC_API_KEY env var。没有此键，表仍然通过PyMuPDF启发式方法提取，但复杂表的准确性较低。视觉提取使用Claude Haiku 4.5的Anthropic Batch API，每张表的成本约为0.016美元，快速缓存降低了大批量的成本。

要完全禁用视觉提取，请执行以下操作：

{
    "vision_enabled": false
}

3.为你的图书馆建立索引

deep-zotero-index -v

要先测试子集，请执行以下操作：

deep-zotero-index --limit 10 -v

这会读取Zotero SQLite数据库（只读，在Zotero打开时是安全的），从每个PDF中提取文本/表格/图形，对文本进行分块，通过Gemini嵌入，并将所有内容存储在ChromaDB中。

CLI选项：

索引器是增量的，它只处理索引中没有的项。使用 --force 变更后 chunk_size, embedding_dimensions，或 ocr_language.

您还可以通过以下方式从MCP客户端触发索引 index_library 工具。

4.注册MCP服务器

添加到您的克劳德代码设置(~/.claude/settings.json):

{
    "mcpServers": {
        "deep-zotero": {
            "command": "/path/to/.venv/bin/python",
            "args": ["-m", "deep_zotero.server"]
        }
    }
}

在Windows上：

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

重新启动克劳德代码。所有13个工具都将可用。

______________________________________________________________________

配置参考

佐特罗

嵌入

分块

视觉

重排序

光学字符识别

OpenAlex

______________________________________________________________________

MCP工具

语义搜索

search_papers --段落级语义搜索。返回与周围上下文匹配的文本，按综合得分（相似度×节权重×期刊权重）重新排序。支持 required_terms 为了将语义搜索与精确的单词匹配相结合，每个术语都必须作为一个完整的单词出现在文章中。

参数： query, top_k (1-50), context_chunks (0-3), year_min, year_max, author, tag, collection, chunk_types （文本/图形/表格）， section_weights, journal_weights, required_terms （文章中必须出现的单词列表）。

search_topic --论文级主题搜索，按文档进行重复数据消除。按纸张分组，按平均值和最佳复合相关性得分。

参数： query, num_papers (1-50), year_min, year_max, author, tag, collection, chunk_types, section_weights, journal_weights.

search_tables --对表内容（标题、单元格、标题）进行语义搜索。以markdown形式返回表。

参数： query, top_k (1-30), year_min, year_max, author, tag, collection, journal_weights.

search_figures --对图形标题进行语义搜索。返回图形元数据和提取的PNG的路径。

参数： query, top_k (1-30), year_min, year_max, author, tag, collection.

布尔搜索

search_boolean --通过Zotero的原生全文索引进行精确的单词匹配。返回与AND/OR单词查询匹配的论文（不是段落）。没有短语搜索，没有词干。

参数： query （空格分隔的术语）， operator （和/或）， year_min, year_max.

上下文扩展

get_passage_context --围绕以下段落展开上下文 search_papers。对于表格结果，请通过 table_page 和 table_index 查找引用表格的正文。

参数： doc_id, chunk_index, window (1-5), table_page, table_index.

引文图（OpenAlex）

要求文档在Zotero中有DOI。

find_citing_papers --引用特定文件的论文。参数： doc_id, limit (1-100).

find_references --文件引用的论文。参数： doc_id, limit (1-100).

get_citation_count --引文和参考文献计数。参数： doc_id.

指标管理

index_library --从MCP客户端触发索引。参数： force_reindex, limit, item_key, title_pattern, no_vision.

get_index_stats --文档/块/表/图计数、章节覆盖率、期刊覆盖率。

get_reranking_config --当前重新排序权重和有效覆盖值。

get_vision_costs -愿景API批量使用和成本摘要。参数： last_n （要显示的最新条目）。

______________________________________________________________________

重排序

搜索结果评分：

composite_score = similarity^alpha * section_weight * journal_weight

默认截面权重：

默认日记账权重：Q1=1.0，Q2=0.85，Q3=0.65，Q4=0.45。

通过以下方式覆盖每次呼叫 section_weights 和 journal_weights 参数。将某个部分设置为0以将其排除。完全禁用重新分级 "rerank_enabled": false.

______________________________________________________________________

共享筛选器参数

______________________________________________________________________

调试查看器

tools/debug_viewer.py 是一个PyQt6浏览器，用于检查ChromaDB索引——查看论文、表格（渲染的markdown与PDF）、图形和单个块。

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