Scholar RAG MCP server

scholar-rag-mcp

<!-- mcp-name: io.github.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

extraction (local heuristics, CrossRef, optional GROBID) -> cleaning -> section annotation -> deterministic chunking (configurable 300/1500/100 chars) -> embedding.

• Real ingestion pipeline: MinerU PDF parsing (python/cli/api backends) -> metadata

metadata filtering (doc_id, section, year, journal, ...) evaluated inside the Qdrant index. 100k-chunk p95 query latency < 1s (see docs/perf-report.md).

• Fast retrieval at scale: embedding first-pass + cross-encoder re-rank, optional

get_job; safe to restart (interrupted jobs are recovered and skipped on re-run).

• Async jobs: createkb/adddocument are background jobs with progress queryable via

pages on demand*.

• Context-safe reading: paginated getdocumenttext with hard size caps; *outline first,

removedocument, getdocument, getdocumenttext, listdocuments, searchdocuments, searchchunks, getjob.

• 11 MCP tools over stdio: listkbs, createkb, deletekb (two-phase), adddocument,

(default location is platform-specific, see Data layout); Qdrant is either auto-launched (single binary, version-pinned) or connected to an external instance.

• Self-contained storage: knowledge bases live under a single data directory

Installation

scholar-rag-mcp runs on Linux x64, Windows x64 and macOS (Intel and Apple Silicon). It is published on PyPI; the standard way to run it is with uv (a suitable Python 3.12 is fetched automatically):

uvx scholar-rag-mcp             # download and start the MCP server (stdio)

No repository checkout is needed. Configure model endpoints and storage with SCHOLARRAG environment variables or /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 --with-mineru # install via uv, provision managed MinerU, register MCP clients
uvx scholar-rag-mcp install              # MCP only; bring your own parse service (see PDF parsing)
scholar-rag-mcp uninstall                # unregister clients and remove the package

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 SCHOLARRAG 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.

Shortened. The full README is on GitHub.