minirag-mcp — Claude Code MCP server: local search over your docs
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.
claude mcp add --env BASE_DIR=<BASE_DIR> --env BASE_DIRS=<BASE_DIRS> --env DB_PATH=<DB_PATH> --env CACHE_DIR=<CACHE_DIR> --env MODEL_NAME=<MODEL_NAME> --transport stdio minirag-mcp -- uvx minirag-mcpWhat minirag-mcp 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.
What it helps with
- 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 for the agent
- 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
How to install minirag-mcp
Platform CLI
claude mcp add --env BASE_DIR=<BASE_DIR> --env BASE_DIRS=<BASE_DIRS> --env DB_PATH=<DB_PATH> --env CACHE_DIR=<CACHE_DIR> --env MODEL_NAME=<MODEL_NAME> --transport stdio minirag-mcp -- uvx minirag-mcpReplace <…> 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 <command>
Platform CLI
codex mcp add minirag-mcp --env BASE_DIR=<BASE_DIR> --env BASE_DIRS=<BASE_DIRS> --env DB_PATH=<DB_PATH> --env CACHE_DIR=<CACHE_DIR> --env MODEL_NAME=<MODEL_NAME> -- uvx minirag-mcpReplace <…> 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 <command>
Config file
{
"mcpServers": {
"minirag-mcp": {
"command": "uvx",
"args": [
"minirag-mcp"
],
"env": {
"BASE_DIR": "<BASE_DIR>",
"BASE_DIRS": "<BASE_DIRS>",
"DB_PATH": "<DB_PATH>",
"CACHE_DIR": "<CACHE_DIR>",
"MODEL_NAME": "<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 <command>
Config file
{
"servers": {
"minirag-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"minirag-mcp"
],
"env": {
"BASE_DIR": "<BASE_DIR>",
"BASE_DIRS": "<BASE_DIRS>",
"DB_PATH": "<DB_PATH>",
"CACHE_DIR": "<CACHE_DIR>",
"MODEL_NAME": "<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 <command>
Platform CLI
gemini mcp add -e BASE_DIR=<BASE_DIR> -e BASE_DIRS=<BASE_DIRS> -e DB_PATH=<DB_PATH> -e CACHE_DIR=<CACHE_DIR> -e MODEL_NAME=<MODEL_NAME> minirag-mcp uvx minirag-mcpReplace <…> 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 <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about minirag-mcp
How do I install minirag-mcp in Claude Code?
Run claude mcp add minirag-mcp -- uvx minirag-mcp. To set paths and the model, use `claude mcp add --env BASE_DIR=<BASE_DIR> --env BASE_DIRS=<BASE_DIRS> --env DB_PATH=<DB_PATH> --env CACHE_DIR=<CACHE_DIR> --env MODEL_NAME=<MODEL_NAME> --transport stdio minirag-mcp -- uvx minirag-mcp`.
What does minirag-mcp do?
It indexes a folder of documents and serves hybrid search over them: vector similarity plus a keyword boost for exact terms. Everything runs locally; the network is used only for the first embedding-model download and for an explicit URL fetch.
Which file formats does it support?
Twelve formats through markitdown: PDF, DOCX, PPTX, XLSX, HTML, CSV, EPUB, Jupyter notebooks, Markdown and plain text. Text, markdown and HTML can also be ingested directly.
