# io.github.sfrangulov/minirag-mcp (pypi · minirag-mcp)

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

- Trust score: 67/100 (medium)
- Change this week: +5
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-19

## Components

- pypi · `minirag-mcp`: 67/100 (this document), [markdown](https://verifymcp.io/servers/sfrangulov-minirag-mcp/minirag-mcp.md), [page](https://verifymcp.io/servers/sfrangulov-minirag-mcp/minirag-mcp)

## Channel facts

- Registry: `pypi`
- Package: `minirag-mcp`
- Version: `0.6.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-19.

- **Supply Chain Security**: 99/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised native-build step with no shell scripting around it.
  - 14 of 83 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: no license is declared.
  - Actively maintained (last published 9 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 67/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2067 tokens (~187/item across 11 items; 11 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 33/100
  - Stability observed for 10 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 71/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add sfrangulov-minirag-mcp -- uvx minirag-mcp
```

### Codex

```bash
codex mcp add sfrangulov-minirag-mcp -- uvx minirag-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sfrangulov-minirag-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "minirag-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sfrangulov-minirag-mcp --command uvx --arg minirag-mcp
```

### Hermes

```yaml
mcp_servers:
  sfrangulov-minirag-mcp:
    command: "uvx"
    args: ["minirag-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "sfrangulov-minirag-mcp": {
      "command": "uvx",
      "args": [
        "minirag-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-19 (score 67, +1)

No change was recorded against any check on this day. Stability & Change Management went from 30 to 33. That category is still filling its 30-day observation window: 9 days of observed history at the previous scan, 10 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-17 (score 66, +4)

- [functional regression] Security disclosure: unverified → fail
- [functional improvement] Stability: unverified → 0.27

### 2026-08-16 (score 62, 0)

- [functional regression] Security disclosure: fail → unverified

### 2026-08-11 (score 62, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-08-09 (score 61)

First indexed and scored.

## MCP tools (11)

### `sync_start` (~171 tokens)

Reconcile the index with the document roots (or one path inside them).

Returns a jobId immediately; poll sync_status until state is
'succeeded' or 'failed'. New and changed files are ingested,
byte-identical files skipped, vanished files removed from the index.
Only the latest sync job is retained — starting a new one, or a
server restart, discards the previous job's record.

Only one sync runs against an index at a time. If one is already in
progress — in this server or in another process, such as a
\`minirag-mcp sync` in a terminal — this call fails immediately with a
message identifying it, and no job is started. Single-file ingests and
queries are never blocked by a running sync.

Input parameters:

- `path`

### `sync_status` (~147 tokens)

Poll a sync job started by sync_start.

Returns state ('pending' | 'running' | 'succeeded' | 'failed'),
counts (scanned/ingested/skipped/deleted/unreadable/failed), and any
per-file errors. Only the latest job is retained — an old jobId, or
any jobId from before a server restart, raises an error.

unreadable counts indexed sources this installation cannot read
because an optional extra is absent (images need [ocr]); each one
appears in errors saying it was kept rather than deleted, but it is
not a failure and does not make the job fail.

Input parameters:

- `jobId` (string, required)

### `ingest_file` (~69 tokens)

Ingest or re-ingest one file, replacing any content already indexed for it.

filePath must be an absolute path inside a configured document root.
Re-ingesting an already-indexed file discards its old chunks and
replaces them with freshly parsed ones.

Input parameters:

- `filePath` (string, required)

### `ingest_data` (~108 tokens)

Ingest text/markdown/html content the client holds, under a source id you choose.

format is one of "text", "markdown", or "html" (default "text").
source is a stable identifier you pick, not a filesystem path —
re-using it replaces the previously ingested content for that id,
so reuse the same source to update an item.

Input parameters:

- `data` (string, required)
- `format` (string)
- `source` (string, required)
- `title`

### `ingest_url` (~135 tokens)

Fetch an http(s) URL, convert it to Markdown, and index it.

Only http and https schemes are accepted, and the host must not be a
private or local address (loopback, link-local, private, reserved) —
set ALLOW_PRIVATE_URLS=1 to lift that. This is the one tool that
reaches the network — every other tool works purely against local
files and the local index. source defaults to the URL itself; pass
one to control the index key or to update a previously ingested URL.

Input parameters:

- `source`
- `title`
- `url` (string, required)

### `query_documents` (~331 tokens)

Hybrid search: semantic similarity plus a keyword boost for exact terms.

Returns `results` — ranked chunks with text, source, title,
chunkIndex, score and parentId — `sources`, the distinct
sources in rank order each with a hits count and a
\`displayPath` to show the user (`source` stays absolute and is
what the other tools take), and `parents`, a map from parentId
to section text. Use `sources` to answer "which documents
cover this topic" without inspecting individual chunks.

\`text` is the passage that matched and that `score` describes.
\`parentId` names the section it sits in — a transcript time
window, a heading section, a slide, a table. Look it up in
\`parents` to read the whole section when the match alone is too
small to act on. A chunk indexed before parent sections existed
has parentId null and no entry; re-sync to fill it in.

topK must be at least 1 and is capped at 100; a larger value is
silently clamped to the cap rather than rejected.

Cite what you take, so the user can verify it, in whatever
language you answer: end with a Sources list, one line per
document you actually used, each line just that document's
\`displayPath` copied verbatim — no [n] markers, nothing else
on the line. Plain text, never a markdown link or file://.

Input parameters:

- `query` (string, required)
- `scope`
- `topK` (integer)

### `read_chunk_neighbors` (~106 tokens)

Read the chunks immediately before and after a search result, for context.

Provide exactly one of filePath (absolute path inside a document
root) or source (the id of a data/url item). before/after control
how many chunks to include on each side of chunkIndex (both
default to 1).

Input parameters:

- `after` (integer)
- `before` (integer)
- `chunkIndex` (integer, required)
- `filePath`
- `source`

### `read_file` (~142 tokens)

Read a source's entire indexed content as Markdown.

The document is reconstructed from its chunks, not concatenated
from them: the context each chunk repeats so its own vector
carries it — a heading breadcrumb, a time-window label, a table's
header row — is emitted once, where the document had it.

Provide exactly one of filePath (absolute path inside a document
root) or source (the id of a data/url item). The response holds
the full document text, so large documents produce large
responses — prefer read_chunk_neighbors when only the context
around one chunk is needed.

Input parameters:

- `filePath`
- `source`

### `list_files` (~221 tokens)

List files found on disk under the document roots, plus indexed data/url sources.

Each disk file is reported with a state: "ingested" (index matches
disk), "stale" (changed on disk since it was indexed),
"stale_scheme" (unchanged on disk, but indexed under an older
chunking scheme, so its vectors are not comparable with current
ones), "not_ingested" (never indexed), or "unreadable" (indexed and
still on disk, but of a type this installation cannot read because
an optional extra is absent — images need [ocr]). Everything but
"ingested" and "unreadable" needs a sync_start; an "unreadable"
source is kept as indexed and no sync can refresh it here.
"stale_scheme" is the per-source view of what status reports as
staleChunkCount. Data and url sources have no disk state to compare
against, so they are "ingested" or "stale_scheme".

Input parameters:

- `scope`

### `delete_file` (~88 tokens)

Delete an indexed file, data item, or url item from the index.

Provide exactly one of filePath (absolute path inside a document
root) or source (the id of a data/url item). This only removes the
index entry — a file left in place under a document root is
re-ingested by a later sync_start.

Input parameters:

- `filePath`
- `source`

### `status` (~198 tokens)

Report configuration and index status. Works even when configuration is invalid.

Always includes version. When configuration is valid, also includes
roots, dbPath, model, hybridWeight, and chunkCount/sourceCount (both
present on every call, 0 before anything is indexed) — or, if opening
the index itself fails, indexError instead of the counts. When
configuration is invalid, includes configError instead, and every
other tool raises an error referencing it until the configuration is
fixed.

chunkScheme is the chunking scheme the index is being written with.
staleChunkCount counts chunks still stored under an older scheme —
when it is above zero, schemeWarning explains that those chunks need
a re-sync to be rebuilt.

ocr names the OCR engine this install can use, or is "unavailable"
when the optional extra is missing — scanned PDFs and images cannot
be indexed then, and ocrHint says what to install.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/sfrangulov-minirag-mcp/minirag-mcp#diagnostics

## Score history

- 2026-08-19: 67
- 2026-08-18: 66
- 2026-08-17: 66
- 2026-08-16: 62
- 2026-08-15: 62
- 2026-08-14: 62
- 2026-08-13: 62
- 2026-08-12: 62
- 2026-08-11: 62
- 2026-08-10: 61
- 2026-08-09: 61

## Links

- PyPI project: https://pypi.org/project/minirag-mcp/
- Socket report: https://socket.dev/pypi/package/minirag-mcp
- Repository: https://github.com/sfrangulov/minirag-mcp
- Changelog RSS feed: https://verifymcp.io/servers/sfrangulov-minirag-mcp/minirag-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/sfrangulov-minirag-mcp/minirag-mcp.json
- HTML version of this page: https://verifymcp.io/servers/sfrangulov-minirag-mcp/minirag-mcp