# minirag-mcp An MCP server that indexes a folder of documents and answers with hybrid search: vector similarity plus exact keyword matches. Files stay on your machine. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 58 - Author: sfrangulov - License: MIT · policy=link-only · description only; the file stays with the author - Source: https://github.com/sfrangulov/minirag-mcp - Updated: 2026-10-23 - HTML: https://affpapa.org/en/nevibecode/mcp/minirag-mcp ## What it does Point the server at a folder and it builds an index over the contents. Search fuses vector similarity with LanceDB BM25 keyword ranking, so error codes and exact identifiers show up next to passages that mean the same thing. The `find_mentions` tool lists every document holding a word or phrase and reports how many documents it went through. Twelve formats are parsed with `markitdown`: PDF, DOCX, PPTX, XLSX, HTML, CSV, EPUB, Jupyter notebooks, Markdown and plain text. You can also ingest text, markdown and HTML directly, or fetch a page by URL. Scanned pages are recognized on the CPU with the optional `[ocr]` extra; document labels by kind, project and date come with `[classify]`. Each file is converted once at ingest, and a question pulls back only the sections that answer it instead of the whole file. Startup runs through `uvx minirag-mcp`, which resolves the package from PyPI on first use, so the first launch is slow and later ones are not. The embedding model downloads once as well. Indexing and querying local files never touch the network. One catch: `claude mcp add` writes the entry without running the command, so a package that cannot be resolved still looks like a working setup until the client tries to start the server and nothing comes up. Check the version before you paste the line. ## Requirements - Needs: Python and uv (commands run via uvx) - Environment variables: `BASE_DIR`, `BASE_DIRS`, `DB_PATH`, `CACHE_DIR`, `MODEL_NAME`, `MAX_FILE_SIZE`, `CHUNK_TOKEN_BUDGET`, `RAG_HYBRID_WEIGHT`, `RAG_GROUPING`, `RAG_MAX_DISTANCE` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env BASE_DIR= --env BASE_DIRS= --env DB_PATH= --env CACHE_DIR= --env MODEL_NAME= --transport stdio minirag-mcp -- uvx minirag-mcp ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from minirag-mcp ### Codex **Platform CLI** ```bash codex mcp add minirag-mcp --env BASE_DIR= --env BASE_DIRS= --env DB_PATH= --env CACHE_DIR= --env MODEL_NAME= -- uvx minirag-mcp ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from minirag-mcp ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "minirag-mcp": { "command": "uvx", "args": [ "minirag-mcp" ], "env": { "BASE_DIR": "", "BASE_DIRS": "", "DB_PATH": "", "CACHE_DIR": "", "MODEL_NAME": "" } } } } ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from minirag-mcp ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "minirag-mcp": { "type": "stdio", "command": "uvx", "args": [ "minirag-mcp" ], "env": { "BASE_DIR": "", "BASE_DIRS": "", "DB_PATH": "", "CACHE_DIR": "", "MODEL_NAME": "" } } } } ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from minirag-mcp ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e BASE_DIR= -e BASE_DIRS= -e DB_PATH= -e CACHE_DIR= -e MODEL_NAME= minirag-mcp uvx minirag-mcp ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from minirag-mcp ## When to use it - find every mention of an error code across a document folder - search PDFs and scans without uploading files anywhere - get answers from your own documents instead of the model's memory - tell near-duplicate document versions apart and see how much text they share - search by filename when the heading inside the document says nothing useful ## Example prompts - Index the docs folder and find every mention of `ERR_CONN_RESET` - How many documents contain the phrase "statement of work"? - Find the section about rate limits in the PDFs I ingested ## Similar - [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989 - [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918 - [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115 - [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160 - [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392 - [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md