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

• Hybrid search — vector similarity (fastembed/ONNX) fused with keyword ranking (LanceDB BM25 full-text search) by weighted Reciprocal Rank Fusion, so exact identifiers and error codes surface alongside semantically similar passages.
• Filenames are searchable — keyword search covers document titles as well 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.
• Multilingual by default — the default embedding model covers 50+ languages, so English and Russian corpora both work out of the box.
• Chunks sized in tokens, passages returned whole — what gets ranked is a 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.
• 12 file formats ingested via markitdown (PDF, DOCX, PPTX, XLSX, HTML, CSV, EPUB, Jupyter notebooks, Markdown, and plain text), plus direct text/markdown/HTML ingestion and URL fetching.
• Scans, with the optional [ocr] extra — image-only PDFs are recognized page by page and standalone images become documents, locally, on the CPU. See OCR for scanned documents.
• Searches without being asked — the server ships a routing policy that 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.
• MCP server and CLI over the same index — inspect and manage the index from a terminal without going through an MCP client.
• Degrades gracefully — a broken configuration doesn't crash the server; every tool reports the error and status always answers.
• 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.

uvx resolves that name from PyPI, so the snippets below work from release 0.1.0 onward; on an earlier revision use From an unreleased revision instead. That distinction is worth checking before you paste: claude mcp add writes the entry without ever running the command, so an unresolvable package looks like a successful setup and only fails later, silently, when the client tries to launch the server.

Claude Code

claude mcp add minirag --scope user --env BASE_DIR=/absolute/path/to/docs \
  -- uvx minirag-mcp

Claude Desktop

Edit the config file — create it if it does not exist:

{
  "mcpServers": {
    "minirag": {
      "command": "/absolute/path/to/uvx",
      "args": ["minirag-mcp"],
      "env": {
        "BASE_DIR": "/absolute/path/to/docs"
      }
    }
  }
}

Then quit Claude Desktop completely (Cmd+Q on macOS, not just closing the window) and reopen it. The config is read at launch; closing the window leaves the old process running with the old config.

Two things that catch people out:

Give command an absolute path. Desktop apps do not inherit your shell's PATH. uvx usually lives in ~/.local/bin, which is not on the PATH a GUI-launched process sees, so a bare "uvx" fails with nothing useful in the UI. Run which uvx and paste the result. The other snippets on this page can use a bare uvx because a terminal-launched client has your PATH.

Merge, do not replace. If the file already exists it holds your other servers and preferences under the same top-level object — add minirag inside the existing mcpServers, and leave everything else alone. Back the file up first; a malformed JSON file makes Desktop start with no servers at all and says little about why.

To check the config before restarting, run the same command by hand — it should print your configuration and exit:

BASE_DIR=/absolute/path/to/docs /absolute/path/to/uvx minirag-mcp status

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "minirag": {
      "command": "uvx",
      "args": ["minirag-mcp"],
      "env": {
        "BASE_DIR": "/absolute/path/to/docs"
      }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.minirag]
command = "uvx"
args = ["minirag-mcp"]

[mcp_servers.minirag.env]
BASE_DIR = "/absolute/path/to/docs"

From an unreleased revision

To run a revision that hasn't been released to PyPI — an unreleased fix, or one specific commit — install from this repository instead. In any snippet above, replace uvx minirag-mcp with:

uvx --from git+https://github.com/sfrangulov/minirag-mcp minirag-mcp

As an argument list, that is ["--from", "git+https://github.com/sfrangulov/minirag-mcp", "minirag-mcp"]. Append @<tag-or-sha> to the URL to pin a revision.

From a clone

For development, or to run the CLI against a working tree you can edit:

git clone https://github.com/sfrangulov/minirag-mcp
cd minirag-mcp
uv sync
uv run minirag-mcp status --base-dir /absolute/path/to/docs

First use

The index starts empty — nothing is scanned until you ask for it:

1. Ask your client to sync: "sync minirag" (calls sync_start, then poll sync_status until it reports succeeded). From a terminal you can do the same thing synchronously: minirag-mcp sync --base-dir /absolute/path/to/docs.
2. Then query: "search minirag for ..." (calls query_documents).

The first sync (or the first ingest of any kind) downloads the embedding model — see Requirements.

Requirements

• Python 3.11+
• uv (provides uvx)
• ~220 MB of disk space and a network connection the first time a document is ingested — fastembed downloads the quantized ONNX weights for the default model and caches them; every ingestion after that is fully offline.

Supported Content

Files under the document root(s) with one of these 12 extensions are picked up by sync_start/sync and ingest_file/ingest, converted to Markdown by markitdown:

.md .markdown .txt .pdf .docx .pptx .xlsx .html .htm .csv .epub .ipynb

A scan skips dot-prefixed names and the ~$… lock files Word, Excel and PowerPoint keep beside every open document. Such a lock file carries the extension of the document it guards but holds none of its content, so before it was skipped a sync failed on it and sync exited 1 while somebody had a document open.

Embedded pictures are not indexed. markitdown inlines each one as an ![alt](data:image/png;base64,…) placeholder — on one measured corpus of office documents that was 8.5% of all chunks — so the placeholder is removed before chunking and only its alt text is kept. Image links that point at a path or an http URL are references, not inlined pictures, and stay as written, as does a data: URI inside a fenced code block.

A PDF that is a scan carries no text to convert, and image files are not in that list at all. Both need the optional [ocr] extra — see OCR for scanned documents.

Two more ways to get content in without a file on disk:

• ingest_data — hand the server text, Markdown, or HTML content directly (format: text|markdown|html), under a source id you choose.
• ingest_url — the server fetches an http/https URL itself via markitdown's convert_url (YouTube, Wikipedia, and RSS get format-specific handling automatically). This is the one tool that reaches the network. Private and local hosts are refused unless ALLOW_PRIVATE_URLS says otherwise — see Security and Operation.

OCR for scanned documents

A scanned PDF is a picture of a page. markitdown finds no text in it, so the document reaches the index empty — which is to say it does not reach the index at all. The optional [ocr] extra reads those pages locally, on the CPU (RapidOCR on the same ONNX runtime the embedding model already uses), and turns standalone image files into documents.