English Français العربية

MiniRAG

Official registry AI and agents

Lightweight self-hosted RAG knowledge base with hybrid retrieval and cited answers.

Source code Documentation

What can you do with MiniRAG?

  • Hybrid retrieval — in-memory cosine + SQLite FTS5 (BM25), fused with RRF; optional LLM rerank
  • Cited answers — clickable [n] citations; only sources actually cited are displayed
  • Streaming web UI — SSE, typewriter rendering, markdown, retrieval-mode switcher (vector / hybrid / rerank)
  • Small footprint — single process, ~250MB RSS, runs on a 1GB VPS
  • Multiple interfaces — MCP server (SSE transport), REST API, web UI, WeChat Work callback integration

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

Remote (sse)
Claude Code 
claude mcp add --transport sse minirag 'https://minirag.kimelody.de5.net/sse' --header 'Authorization: <HTTP Basic auth: '\''Basic '\'' + base64('\''demo:<access key>'\''). Request the access key from the repo owner (see README).>'
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "minirag": {
            "type": "sse",
            "url": "https://minirag.kimelody.de5.net/sse",
            "headers": {
                "Authorization": "<HTTP Basic auth: 'Basic ' + base64('demo:<access key>'). Request the access key from the repo owner (see README).>"
            }
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. MiniRAG
  2. Features
  3. Quick start
  4. Configuration
  5. MCP
  6. REST API
  7. Evaluation
  8. Build from source
  9. 中文说明
  10. License

MiniRAG

A self-hosted RAG knowledge base in a single Spring Boot process: SQLite storage, hybrid retrieval, cited answers, and a built-in MCP server. No vector database, no message queue.

Live demo (ask the owner for the access code) · Evaluation report

Features

  • Hybrid retrieval — in-memory cosine + SQLite FTS5 (BM25), fused with RRF; optional LLM rerank
  • Cited answers — clickable [n] citations; only sources actually cited are displayed
  • Streaming web UI — SSE, typewriter rendering, markdown, retrieval-mode switcher (vector / hybrid / rerank)
  • Small footprint — single process, ~250MB RSS, runs on a 1GB VPS
  • Multiple interfaces — MCP server (SSE transport), REST API, web UI, WeChat Work callback integration

Quick start

docker run -d --name minirag -p 18090:18090 --memory 512m \
  -v $(pwd)/data:/app/data \
  -e DEEPSEEK_API_KEY=sk-... \
  -e EMBEDDING_API_KEY=sk-... \
  ghcr.io/kimelody/minirag:latest

Open http://localhost:18090 and start asking. Data lives in ./data (SQLite, created automatically).

Configuration

EnvRequiredDefaultDescription
DEEPSEEK_BASE_URLnohttps://api.deepseek.comAny OpenAI-compatible chat endpoint
DEEPSEEK_API_KEYyes—Chat model API key
EMBEDDING_BASE_URLnohttps://api.siliconflow.cn/v1OpenAI-compatible embeddings endpoint
EMBEDDING_API_KEYyes—Embeddings API key
EMBEDDING_MODELnoBAAI/bge-m3Embedding model
DEMO_KEYno—Visitor access code for read APIs; unset = open (local dev)
ADMIN_KEYno—Admin key required for ingest APIs

MCP

Two tools: query(question, mode?) — ask and get a cited answer; ingest_text(docId, text, adminKey) — add a document.

{
  "mcpServers": {
    "minirag": {
      "url": "http://localhost:18090/sse"
    }
  }
}

The hosted demo endpoint requires basic auth: https://minirag.kimelody.de5.net/sse (ask the owner for credentials).

REST API

MethodPathDescription
POST/api/chatAsk; returns answer + cited sources (JSON)
POST/api/chat/streamSame, streamed as SSE (meta / token / sources / done)
GET/api/search?q=&mode=Retrieval debug: vector \hybrid \rerank
POST/api/documents/textIngest {docId, text} (requires X-Admin-Key)
POST/api/documentsIngest an uploaded file, multipart (requires X-Admin-Key)

Evaluation

An eval harness ships in eval/: labeled question sets, Top-1 / Recall / MRR scoring over three retrieval modes — hybrid+rerank reaches Top-1 100% / MRR 1.0 on the demo set (report); a 20-question labor-law evaluation with corpus-cleaning scripts lives in eval/law/. Bring your own corpus; raw source texts are not redistributed.

Build from source

mvn package
java -jar target/minirag-0.1.0-SNAPSHOT.jar

Requires Java 21. API keys can be put in a .env file in the working directory (git-ignored).

中文说明

单进程私有化 RAG 知识库：SQLite 存储 + 混合检索（向量 + BM25，RRF 融合，可选 LLM 重排），回答带可点击引用角标，自带网页演示、REST API 与 MCP server（SSE），内存占用约 250MB，1GB 小服务器可跑。在线演示（访问码联系作者）。

License

MIT

Frequently asked questions

What is MiniRAG?

Lightweight self-hosted RAG knowledge base with hybrid retrieval and cited answers.

How do I install MiniRAG?

It runs as a remote server. In Claude Code: claude mcp add --transport sse minirag 'https://minirag.kimelody.de5.net/sse' --header 'Authorization: <HTTP Basic auth: '\''Basic '\'' + base64('\''demo:<access key>'\''). Request the access key from the repo owner (see README).>'. For other clients, paste the JSON configuration from this page into their MCP settings.

Does MiniRAG need an API key?

Yes. It expects Authorization, which you set in its configuration.

Is MiniRAG open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains MiniRAG?

It is published by KiMelody. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.