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 additionally deletes the data directory after explicit confirmation (skip the prompt with --yes).

From source (development)

Requires pixi. From the repository root:

pixi install                      # installs the default environment

The pixi environments are locked for all four supported targets. The project defines two pixi environments, each serving a different purpose:

Verify your environment with the built-in doctor:

pixi run python scripts/doctor.py

Model deployment

Environment ('chat', 'embed' and 'rerank' clients) expects OpenAI-compatible HTTP endpoints. scripts/serve_models.sh launches three vLLM instances for the reference model set:

# point *_MODEL at your local model directories, then:
bash scripts/serve_models.sh

SCHOLAR_RAG_CHAT_MODEL, SCHOLAR_RAG_EMBED_MODEL and SCHOLAR_RAG_RERANK_MODEL are required - the script exits with a message listing them if any is unset. Each value must be an absolute path to a local HuggingFace model directory; vLLM serves each model under a short name equal to the directory basename, so the client settings must use that short name (the served name no longer equals the full path). Replace the /path/to/... placeholders in .env.example accordingly. Ports (CHAT_PORT/EMBED_PORT/RERANK_PORT) and GPU ids remain optional with working defaults.

The script passes the vLLM flags verified for the default model set, notably --trust-remote-code, which all three models require on the pinned vLLM (0.27.1). Model load takes several minutes; the script polls health until all three answer.

scripts/serve_models.sh is Linux-only (bash + CUDA + vLLM; vLLM has no Windows support). On Windows/macOS point the *_BASE_URL settings at any OpenAI-compatible server instead - for example Ollama (http://127.0.0.1:11434/v1), LM Studio's local server, or a llama.cpp server - and set each *_MODEL to the model name that server reports. The rerank endpoint must expose /v1/rerank (or leave reranking to the embed-only fallback).

Minimal environment

Start from .env.example and set at least the model endpoints (use the short names the serve script exposes, equal to each model directory's basename):

# data dir is optional - defaults to the platform data directory (see Data layout)
# SCHOLAR_RAG_DATA_DIR=
# SCHOLAR_RAG_QDRANT_STORAGE_DIR=

SCHOLAR_RAG_CHAT_BASE_URL=http://127.0.0.1:8101/v1
SCHOLAR_RAG_CHAT_MODEL=Qwen3.5-0.8B

SCHOLAR_RAG_EMBED_BASE_URL=http://127.0.0.1:8102/v1
SCHOLAR_RAG_EMBED_MODEL=jina-embeddings-v5-text-small

SCHOLAR_RAG_RERANK_BASE_URL=http://127.0.0.1:8103/v1
SCHOLAR_RAG_RERANK_MODEL=jina-reranker-v3.5

The embed model dimension is recorded in kb_meta.json at kb creation, so changing the embedding model later requires a new kb.

PDF parsing (MinerU)

Since v0.4.0 the default parse backend is api. The recommended setup is the managed sidecar, which installs MinerU into an isolated Python 3.12 venv (MinerU requires Python >=3.10,<3.14) and auto-starts mineru-api on first parse:

scholar-rag-mcp install --with-mineru

The first parse triggers MinerU's model download; set MINERU_MODEL_SOURCE=modelscope if you need a China-friendly mirror.

Self-managed alternative: install MinerU in any Python 3.12 environment, run mineru-api --host 127.0.0.1 --port 8010, and keep the defaults (SCHOLAR_RAG_MINERU_BACKEND=api, SCHOLAR_RAG_MINERU_API_URL=http://127.0.0.1:8010).

The python backend (in-process import) and cli backend (subprocess per file) remain available via SCHOLAR_RAG_MINERU_BACKEND.

MCP client setup

Point your MCP client at the uvx entry point and configure the model endpoints in the env block (any OpenAI-compatible server works; see Model deployment). To check that the server starts, run uvx scholar-rag-mcp in a terminal - it waits for an MCP client on stdio (Ctrl+C to exit).

Claude (Claude Desktop / claude CLI)

{
  "mcpServers": {
    "scholar-rag-mcp": {
      "command": "uvx",
      "args": ["scholar-rag-mcp"],
      "env": {
        "SCHOLAR_RAG_CHAT_BASE_URL": "http://127.0.0.1:8101/v1",
        "SCHOLAR_RAG_CHAT_MODEL": "Qwen3.5-0.8B",
        "SCHOLAR_RAG_EMBED_BASE_URL": "http://127.0.0.1:8102/v1",
        "SCHOLAR_RAG_EMBED_MODEL": "jina-embeddings-v5-text-small",
        "SCHOLAR_RAG_RERANK_BASE_URL": "http://127.0.0.1:8103/v1",
        "SCHOLAR_RAG_RERANK_MODEL": "jina-reranker-v3.5"
      }
    }
  }
}

opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scholar-rag-mcp": {
      "type": "local",
      "command": ["uvx", "scholar-rag-mcp"],
      "environment": {
        "SCHOLAR_RAG_CHAT_BASE_URL": "http://127.0.0.1:8101/v1",
        "SCHOLAR_RAG_CHAT_MODEL": "Qwen3.5-0.8B",
        "SCHOLAR_RAG_EMBED_BASE_URL": "http://127.0.0.1:8102/v1",
        "SCHOLAR_RAG_EMBED_MODEL": "jina-embeddings-v5-text-small",
        "SCHOLAR_RAG_RERANK_BASE_URL": "http://127.0.0.1:8103/v1",
        "SCHOLAR_RAG_RERANK_MODEL": "jina-reranker-v3.5"
      }
    }
  }
}

Running from a source checkout instead: use pixi run scholar-rag-mcp as the command (from the repository root) and set the same variables in your shell.

Tools