minirag-mcp
Local-first RAG MCP server giving hybrid search over your own documents.
Tested on Linux
Use it
Linux x86_64
You need first
- Runtimes:
Python 3.11+ - System packages:
uv
install minirag-mcp with uv tool
uv tool install minirag-mcp
Where the README and reality differ
- README: `query_documents` and `list_files` take `labels`, `dateFrom` and `dateTo`
What worked: any labels/dateFrom/dateTo filter is refused without <root>/.minirag/classify.toml, even a date-only filter; created minimal default-facet taxonomy to make it answer - README: `find_mentions` lists every document that mentions a phrase
What worked: installed PyPI v1.0.0 exposes 11 MCP tools with no find_mentions; README describes 12 tools including find_mentions
Check that it works
minirag-mcp --versionThe output should contain “1.0.0”.
Add it to your agent
claude mcp add minirag-mcp -e BASE_DIR='<BASE_DIR>' -- minirag-mcpJSON for Claude Desktop, Cursor and other clients
{
"mcpServers": {
"minirag-mcp": {
"command": "minirag-mcp",
"args": [],
"env": {
"BASE_DIR": "<BASE_DIR>"
}
}
}
}You fill in
BASE_DIR: folder you want indexed (required)
Ask the user for BASE_DIR; pickfit never had a value, so these are placeholders.
Index a folder first with minirag-mcp sync --base-dir <folder>, then add minirag-mcp as a server in your MCP client with BASE_DIR set to that folder.
What it does
- Search your local documents by meaning and keywordTested
How to use it
- Index your folder with
minirag-mcp sync --base-dir <folder>. - Start
minirag-mcpfrom your MCP client with BASE_DIR set to <folder>. - Call the query_documents tool with your query and an optional topK, such as {"query":"<your text>","topK":5}.
- Index your folder with
- Add documents in 12 file formatsTested
How to use it
- Start
minirag-mcpfrom your MCP client with BASE_DIR set to your documents folder. - Call the ingest_data tool with your content, a source name and a format, such as {"data":"<your text>","source":"<name>","format":"markdown"}.
- Start
- List every document that mentions a phraseNot tested
- Filter search results by labels and datesNot shown working
How far pickfit got
Linux x86_64
- Installs
- Connects
- 2 of 4 features work
- Works offline
macOS and Windows: the project says it runs there; pickfit hasn’t tried it.
Good for
- search documents with hybrid semantic and keyword search
- list every document containing a word or phrase
- index a folder of documents for RAG
An alternative to shinpr/mcp-local-rag.
How pickfit tested it
Each run starts from a clean machine and follows the steps above. How pickfit verifies
Linux x86_64
An MCP client called one of its tools
- Replayed from scratch
- Works offline
- Checked on 30 Oct 2026
- Version 1.0.0
An MCP client handshake over stdio listed 11 tools, and a call to query_documents returned a result.