Minirag MCP server

minirag-mcp

<!-- mcp-name: io.github.sfrangulov/minirag-mcp -->

A local-first RAG (retrieval-augmented generation) MCP server. Point it at a folder of documents and it gives your MCP client (Claude Code, Cursor, Codex, ...) hybrid search — semantic vector similarity plus a keyword boost for exact terms — over that content.

Nothing leaves your machine except two things: the one-time embedding-model download on first use, and the explicit ingest_url call when you ask it to fetch a web page. Ingesting local files, indexing, and querying never touch the network.

It is a Python, MCP-native analog of shinpr/mcp-local-rag (TypeScript), built on fastmcp, fastembed, and LanceDB.

Features

ranking (LanceDB BM25 full-text search) by weighted Reciprocal Rank Fusion, so exact identifiers and error codes surface alongside semantically similar passages.

• Hybrid search — vector similarity (fastembed/ONNX) fused with keyword

as body text, and an informative filename becomes the document's title when the document's own heading is boilerplate. In many real document sets the filename is the only place the document code and subject appear at all. See Titles and filenames.

• Filenames are searchable — keyword search covers document titles as well

languages, so English and Russian corpora both work out of the box.

• Multilingual by default — the default embedding model covers 50+

small unit that fits the embedding model's 128-token ceiling; what comes back is the section around it — a transcript time window, a heading section, a slide, a table. See Chunking.

• Chunks sized in tokens, passages returned whole — what gets ranked is a

HTML, CSV, EPUB, Jupyter notebooks, Markdown, and plain text), plus direct text/markdown/HTML ingestion and URL fetching.

• 12 file formats ingested via markitdown (PDF, DOCX, PPTX, XLSX,

page by page and standalone images become documents, locally, on the CPU. See OCR for scanned documents.

• Scans, with the optional [ocr] extra — image-only PDFs are recognized

clients put in front of the model, so a question your documents can answer goes to the index instead of to the model's memory. See Search by Default.

• Searches without being asked — the server ships a routing policy that

from a terminal without going through an MCP client.

• MCP server and CLI over the same index — inspect and manage the index

every tool reports the error and status always answers.

• Degrades gracefully — a broken configuration doesn't crash the server;

• No hidden network calls — see Security and Operation.

Quick Start

Every client below launches the same process; only the config format differs. Replace /absolute/path/to/docs with the folder you want indexed.

The invocation is uvx minirag-mcp. It resolves and caches the package on first run, so start-up is slow once and fast afterwards.

Shortened. The full README is on GitHub.