Minirag Mcp

io.github.sfrangulov/minirag-mcp · v1.0.0

Local-first RAG MCP server: hybrid search over a folder of your own documents

Website Source code Set it up

Connect Runs on your machine

Terminal

claude mcp add minirag-mcp -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> -e MAX_FILE_SIZE=<MAX_FILE_SIZE> -e CHUNK_TOKEN_BUDGET=<CHUNK_TOKEN_BUDGET> -e RAG_HYBRID_WEIGHT=<RAG_HYBRID_WEIGHT> -e RAG_GROUPING=<RAG_GROUPING> -e RAG_MAX_DISTANCE=<RAG_MAX_DISTANCE> -e RAG_MAX_FILES=<RAG_MAX_FILES> -e RAG_INSTRUCTIONS_APPEND=<RAG_INSTRUCTIONS_APPEND> -e ALLOW_PRIVATE_URLS=<ALLOW_PRIVATE_URLS> -- uvx minirag-mcp==1.0.0

claude_desktop_config.json

{
  "mcpServers": {
    "minirag-mcp": {
      "command": "uvx",
      "args": [
        "minirag-mcp==1.0.0"
      ],
      "env": {
        "BASE_DIR": "<BASE_DIR>",
        "BASE_DIRS": "<BASE_DIRS>",
        "DB_PATH": "<DB_PATH>",
        "CACHE_DIR": "<CACHE_DIR>",
        "MODEL_NAME": "<MODEL_NAME>",
        "MAX_FILE_SIZE": "<MAX_FILE_SIZE>",
        "CHUNK_TOKEN_BUDGET": "<CHUNK_TOKEN_BUDGET>",
        "RAG_HYBRID_WEIGHT": "<RAG_HYBRID_WEIGHT>",
        "RAG_GROUPING": "<RAG_GROUPING>",
        "RAG_MAX_DISTANCE": "<RAG_MAX_DISTANCE>",
        "RAG_MAX_FILES": "<RAG_MAX_FILES>",
        "RAG_INSTRUCTIONS_APPEND": "<RAG_INSTRUCTIONS_APPEND>",
        "ALLOW_PRIVATE_URLS": "<ALLOW_PRIVATE_URLS>"
      }
    }
  }
}

~/.cursor/mcp.json

{
  "mcpServers": {
    "minirag-mcp": {
      "command": "uvx",
      "args": [
        "minirag-mcp==1.0.0"
      ],
      "env": {
        "BASE_DIR": "<BASE_DIR>",
        "BASE_DIRS": "<BASE_DIRS>",
        "DB_PATH": "<DB_PATH>",
        "CACHE_DIR": "<CACHE_DIR>",
        "MODEL_NAME": "<MODEL_NAME>",
        "MAX_FILE_SIZE": "<MAX_FILE_SIZE>",
        "CHUNK_TOKEN_BUDGET": "<CHUNK_TOKEN_BUDGET>",
        "RAG_HYBRID_WEIGHT": "<RAG_HYBRID_WEIGHT>",
        "RAG_GROUPING": "<RAG_GROUPING>",
        "RAG_MAX_DISTANCE": "<RAG_MAX_DISTANCE>",
        "RAG_MAX_FILES": "<RAG_MAX_FILES>",
        "RAG_INSTRUCTIONS_APPEND": "<RAG_INSTRUCTIONS_APPEND>",
        "ALLOW_PRIVATE_URLS": "<ALLOW_PRIVATE_URLS>"
      }
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "minirag-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "minirag-mcp==1.0.0"
      ],
      "env": {
        "BASE_DIR": "<BASE_DIR>",
        "BASE_DIRS": "<BASE_DIRS>",
        "DB_PATH": "<DB_PATH>",
        "CACHE_DIR": "<CACHE_DIR>",
        "MODEL_NAME": "<MODEL_NAME>",
        "MAX_FILE_SIZE": "<MAX_FILE_SIZE>",
        "CHUNK_TOKEN_BUDGET": "<CHUNK_TOKEN_BUDGET>",
        "RAG_HYBRID_WEIGHT": "<RAG_HYBRID_WEIGHT>",
        "RAG_GROUPING": "<RAG_GROUPING>",
        "RAG_MAX_DISTANCE": "<RAG_MAX_DISTANCE>",
        "RAG_MAX_FILES": "<RAG_MAX_FILES>",
        "RAG_INSTRUCTIONS_APPEND": "<RAG_INSTRUCTIONS_APPEND>",
        "ALLOW_PRIVATE_URLS": "<ALLOW_PRIVATE_URLS>"
      }
    }
  }
}

Replace the values in angle brackets with your own. Keys stay on your machine; we never see them.

Tools

This server runs locally, so its tools are listed by your MCP client once it starts.

Environment variables

Name	Description
`BASE_DIR` Optional	One document root; also the security boundary for file access. Defaults to the process working directory. Ignored when BASE_DIRS is set.
`BASE_DIRS` Optional	JSON array of document roots, e.g. ["/docs/a", "/docs/b"]. Takes precedence over BASE_DIR. An invalid value is a hard configuration error.
`DB_PATH` Optional	LanceDB index directory. Defaults to <first root>/.minirag/lancedb, so each corpus gets its own index.
`CACHE_DIR` Optional	Embedding model cache. Defaults to the platform user cache dir, so the ~220 MB model is downloaded once and shared.
`MODEL_NAME` Optional	fastembed model id. Changing it makes existing vectors incompatible with new queries; pair with a new DB_PATH or a full re-ingest.
`MAX_FILE_SIZE` Optional	Per-file size limit in bytes, enforced before parsing.
`CHUNK_TOKEN_BUDGET` Optional	Retrieval-unit size in the embedding model's own tokens. Range 16-128; the ceiling is the model's trained sequence length.
`RAG_HYBRID_WEIGHT` Optional	Keyword weight in the weighted RRF fusion, range 0.0-1.0. 0 is vector-only; higher values raise the BM25 contribution.
`RAG_GROUPING` Optional	Result grouping filter. 'similar' keeps only the closest group; 'related' also keeps the next one. Unset means no grouping filter.
`RAG_MAX_DISTANCE` Optional	Drop results whose vector distance exceeds this value. Lower is stricter. Unset means no distance filter.
`RAG_MAX_FILES` Optional	Keep chunks from at most this many best-scoring files. Unset means no per-file filter.
`RAG_INSTRUCTIONS_APPEND` Optional	Extra paragraph appended to the instructions the server hands the client at connect time, for corpus-specific guidance.
`ALLOW_PRIVATE_URLS` Optional	Let ingest_url fetch hosts resolving to loopback, link-local, private, reserved or unspecified addresses. Off by default.

Details

Package	`[email protected]` (PYPI, stdio)
First published	22 Oct 2026
Last updated	22 Oct 2026
Registry name	`io.github.sfrangulov/minirag-mcp`

More search and web servers See all

Live status

Local install

Installed and run on your own machine, so there is no public endpoint to check.

Pair it with live search

Agents that use Minirag Mcp often also need current facts. NestDaddy MCP gives your AI today's internet: web search, real-time breaking news and full page reading in one connector.

See NestDaddy MCP

For maintainers

[![NestDaddy MCP](https://nestdaddy.com/mcp/servers/io-github-sfrangulov-minirag-mcp/badge.svg)](https://nestdaddy.com/mcp/servers/io-github-sfrangulov-minirag-mcp)

Add the badge to your README. It turns green while your server passes our daily check. Listing details come from the official MCP registry; update them there.

Listing data from the official MCP registry. Status and tools from NestDaddy's daily check. Browse all MCP servers.