# minirag-mcp

MCP-сервер, который индексирует папку с документами и даёт гибридный поиск: векторное сходство плюс точные совпадения по словам. Данные не покидают машину.

- MCP-сервер · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 58
- Автор: sfrangulov
- Лицензия: MIT · policy=link-only · показываем только описание, файл — у автора
- Исходник: https://github.com/sfrangulov/minirag-mcp
- Обновлён: 2026-10-23
- HTML: https://affpapa.org/nevibecode/mcp/minirag-mcp

## Что делает

Сервер указывают на папку с файлами, и он строит по ней индекс. Поиск совмещает векторное сходство с ранжированием по ключевым словам через LanceDB BM25, поэтому номера ошибок и точные идентификаторы находятся наравне со смысловыми совпадениями. Инструмент `find_mentions` перечисляет все документы с нужным словом или фразой и сообщает, сколько документов просмотрено.

Разбираются 12 форматов через `markitdown`: PDF, DOCX, PPTX, XLSX, HTML, CSV, EPUB, ноутбуки Jupyter, Markdown и обычный текст. Есть прямая загрузка текста, markdown и HTML, а также получение страницы по URL. Сканы распознаются на CPU, если поставить дополнительный компонент `[ocr]`; метки документов по типу, проекту и дате — с компонентом `[classify]`. Каждый файл преобразуется один раз при загрузке, а на вопрос возвращаются только нужные фрагменты, а не весь документ.

Запуск идёт через `uvx minirag-mcp`, и при первом обращении пакет скачивается из PyPI, поэтому старт будет долгим только раз. Модель эмбеддингов тоже подгружается при первом использовании. Всё остальное — индексация, поиск, работа с локальными файлами — идёт без сети. Правда, `claude mcp add` записывает конфигурацию, не проверяя команду: если пакет не резолвится, настройка выглядит удачной, а сервер молча не поднимется при запуске клиента. Это повод проверить версию перед тем, как вставлять команду.

## Требования
- Нужно: Python и uv (команды через uvx)
- Переменные окружения: `BASE_DIR`, `BASE_DIRS`, `DB_PATH`, `CACHE_DIR`, `MODEL_NAME`, `MAX_FILE_SIZE`, `CHUNK_TOKEN_BUDGET`, `RAG_HYBRID_WEIGHT`, `RAG_GROUPING`, `RAG_MAX_DISTANCE` — это ключи и токены: значения спроси у человека, в репозиторий и общие файлы не записывай.

## Установка

### Claude Code (родная платформа)

**Командой платформы**
```bash
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
```
Вместо <…> подставьте свои значения. Ещё 8 переменных окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from minirag-mcp <команда>

### Codex

**Командой платформы**
```bash
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-mcp
```
Вместо <…> подставьте свои значения. Ещё 8 переменных окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from minirag-mcp <команда>

### Cursor

**Файл настроек**
Файл `.cursor/mcp.json`:
```json
{
    "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>"
            }
        }
    }
}
```
Вместо <…> подставьте свои значения. Ещё 8 переменных окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from minirag-mcp <команда>

### GitHub Copilot

**Файл настроек**
Файл `.vscode/mcp.json`:
```json
{
    "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>"
            }
        }
    }
}
```
Вместо <…> подставьте свои значения. Ещё 8 переменных окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from minirag-mcp <команда>

### Gemini CLI

**Командой платформы**
```bash
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-mcp
```
Вместо <…> подставьте свои значения. Ещё 8 переменных окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from minirag-mcp <команда>

## Когда брать
- найти все упоминания кода ошибки в папке с документами
- искать по PDF и сканам без отправки файлов в облако
- получать ответ из своих документов, а не из памяти модели
- отличить похожие версии одного документа и понять, сколько текста у них общего
- искать по именам файлов, когда заголовок внутри документа ничего не говорит

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md