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 < 1s (see docs/perf-report.md).
• Async jobs: create_kb/add_document are background jobs with progress queryable via get_job; safe to restart (interrupted jobs are recovered and skipped on re-run).
• Context-safe reading: paginated get_document_text with hard size caps; outline first, pages on demand.
• 11 MCP tools over stdio: list_kbs, create_kb, delete_kb (two-phase), add_document, remove_document, get_document, get_document_text, list_documents, search_documents, search_chunks, get_job.
• Self-contained storage: knowledge bases live under a single data directory (default location is platform-specific, see Data layout); Qdrant is either auto-launched (single binary, version-pinned) or connected to an external instance.

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 SCHOLAR_RAG_* environment variables or <data_dir>/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 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 <name> 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 addit

... View full README on GitHub