notwhiteblank/scholar-rag-mcp

> **Status: preview release (v0.4.0).** Interfaces and storage layout may change in future versions.
**scholar-rag-mcp** is a publishable academic-paper knowledge-base MCP tool. Point it at a
folder of PDFs and it ingests each paper through a real parsing pipeline (MinerU), normalizes
metadata, annotates section structure, chunks and embeds the text, and stores everything in
Qdrant - after which an agent (or you) can semantically search chunks, run PubMed-style
document queries, read full text section by section, add/remove single papers, and manage
knowledge bases - all through 11 MCP tools over stdio. Embedding, annotation and re-ranking
run on OpenAI-compatible model services (e.g. vLLM).
Features
- **Real ingestion pipeline**: MinerU PDF parsing (python/cli/api backends) -> metadata
extraction (local heuristics, CrossRef, optional GROBID) -> cleaning -> section annotation
-> deterministic chunking (configurable 300/1500/100 chars) -> embedding.
- **Fast retrieval at scale**: embedding first-pass + cross-encoder re-rank, optional
metadata filtering (doc_id, section, year, journal, ...) evaluated inside the Qdrant
index. 100k-chunk p95 query latency /config.json (see
.env.example); the Qdrant binary used for auto-launch is downloaded per
platform on first use.
One-click install / uninstall
uvx scholar-rag-mcp install installs the package via uv tool install and interactively
walks through the six model-endpoint settings (chat/embed/rerank base URLs and model
names), using the defaults listed in Minimal environment unless a SCHOLAR_RAG_* value or a
--chat-base-url / --chat-model / --embed-base-url / --embed-model /
--rerank-base-url / --rerank-model flag is given; --yes accepts all defaults without
prompting. It then detects the four supported MCP clients (Claude Desktop, Claude Code,
opencode, Codex) and registers the tool by merging the scholar-rag-mcp entry into their
user-level configs, touching only that entry; pass --client to register a single
client. Configs that cannot be parsed (e.g. JSON with comments) are left untouched and a
manual snippet is printed instead.
scholar-rag-mcp uninstall removes the scholar-rag-mcp entry from the detected clients and
runs uv tool uninstall; the knowledge-base data directory is kept. --purge additionally
deletes the data directory after explicit confirmation (skip the prompt with --yes).
From source (development)
Requires pixi. From the repository root:
The pixi environments are locked for all four supported targets. The project
defines two pixi environments, each serving a different purpose:
| Environment | Purpose |
|---|---|
| default | Core runtime + dev tooling (pytest/ruff/mypy). Run the MCP server and all scripts here. |
| mineru | Adds MinerU (==3.4.5) plus its full runtime stack (pinned transformers =3.10, / # SCHOLAR_RAG_DATA_DIR, default: platform data dir (below)
├── kbs/ /
│ ├── kb_meta.json # dimension, chunk config, schema version
│ ├── catalog.sqlite3 # documents / authors / keywords / chunks + FTS5
│ └── documents/ / # source.pdf, full_text.md, sections.json