Skip to main content
Glama

sqlite-rag-mcp

100% offline RAG as an MCP server — index your documents into SQLite (sqlite-vec + FTS5, hybrid RRF search, local Ollama embeddings) and search them from Claude. Your documents never leave your machine.

🇺🇸 English

Why

Most RAG stacks ship your documents to a hosted vector database and an embeddings API. This one doesn't. Everything — storage, vectors, lexical index, embeddings — runs locally:

  • One SQLite file is the whole index. No services to run, nothing to babysit. Back it up with cp.

  • Hybrid search: sqlite-vec vector KNN + FTS5 BM25, fused with Reciprocal Rank Fusion (RRF) — better recall than either alone.

  • Local embeddings via Ollama (nomic-embed-text by default).

  • Graceful degradation: if Ollama isn't running, indexing and search still work in lexical (FTS5) mode with an explicit warning. Search never breaks.

Architecture

flowchart LR
    subgraph Claude["Claude Code / Claude Desktop"]
        C[MCP client]
    end
    subgraph Server["sqlite-rag-mcp (stdio)"]
        T1[index_documents]
        T2[search]
        T3[get_chunk]
        T4[stats]
        F{{RRF fusion}}
    end
    subgraph Local["Your machine only"]
        DB[(SQLite<br/>chunks + FTS5 + vec0)]
        O[Ollama<br/>nomic-embed-text]
        MD[/your .md / .txt files/]
    end
    C <-->|MCP over stdio| T1 & T2 & T3 & T4
    T1 --> MD
    T1 --> O
    T1 --> DB
    T2 --> F
    F -->|semantic KNN| DB
    F -->|lexical BM25| DB
    T2 -.->|embed query| O
    O -.->|offline? fall back to FTS5| F

Install

Requires Python ≥ 3.10. Not yet published to PyPI — install from a clone of this repository:

git clone https://github.com/giuseppeferretti/sqlite-rag-mcp
cd sqlite-rag-mcp
pip install .

For semantic search, also install Ollama and pull the embedding model:

ollama pull nomic-embed-text   # optional — lexical search works without it

Configure Claude Code / Claude Desktop

Add to your MCP settings (claude mcp add or claude_desktop_config.json):

{
  "mcpServers": {
    "sqlite-rag": {
      "command": "sqlite-rag-mcp",
      "env": {
        "SQLITE_RAG_DB": "~/.local/share/sqlite-rag-mcp/index.db"
      }
    }
  }
}

Or with Claude Code CLI:

claude mcp add sqlite-rag -- sqlite-rag-mcp

Environment variable

Default

Purpose

SQLITE_RAG_DB

~/.local/share/sqlite-rag-mcp/index.db

Index database path

OLLAMA_HOST

http://localhost:11434

Ollama endpoint

SQLITE_RAG_EMBED_MODEL

nomic-embed-text

Embedding model

SQLITE_RAG_CHUNK_TOKENS

800

Chunk size (approx. tokens)

SQLITE_RAG_CHUNK_OVERLAP

100

Chunk overlap (approx. tokens)

Tools

index_documents(path, glob="**/*.md") — index text/markdown files from a directory. Unchanged files (same SHA-256) are skipped, changed files are re-chunked and re-embedded.

"Index everything under ~/notes" → index_documents(path="~/notes") → {"files_indexed": 42, "chunks_added": 310, "chunks_embedded": 310, "warnings": []}

search(query, k=8, mode="hybrid") — search the index. Modes: hybrid (RRF fusion, default), semantic (vector KNN), lexical (FTS5 BM25). With Ollama offline, hybrid/semantic fall back to lexical and the response carries a warning — it never errors.

"How do I rotate API tokens?" → {"mode_used": "hybrid", "results": [{"chunk_id": 17, "score": 0.0325, "snippet": "Generate a token with…", "source": "…/authentication.md", "title": "Authentication and API Tokens", "matched_by": "semantic+lexical"}]}

get_chunk(chunk_id) — full text + source of a chunk returned by search.

stats() — document/chunk/embedding counts, DB path and size, Ollama availability.

CLI indexing (outside MCP)

python -m sqlite_rag_mcp.index ~/notes --glob "**/*.md"
python -m sqlite_rag_mcp.index ~/docs --glob "**/*.txt" --db /tmp/docs.db

How search works

  1. The query is embedded locally (Ollama) and run against the vec0 KNN index; in parallel a sanitized, OR-expanded prefix query runs against FTS5 (BM25).

  2. Both rankings are fused with Reciprocal Rank Fusion: score(chunk) = Σ 1/(60 + rank + 1) across the two lists — a rank-based method that needs no score calibration between BM25 and cosine distance.

  3. Top-k fused chunks are returned with snippet, source path, and which ranker(s) matched them.

Provenance

This server is the extracted, genericized search core of a production RAG system that indexes and answers questions over a company's document corpus — fully offline, on commodity hardware. Case study at portfolio.iterlabs.com.br.

Development

pip install -e ".[dev]"
pytest   # includes a real stdio smoke test that spawns the server and drives it with the MCP SDK client

Related MCP server: Hoard

🇧🇷 Português

RAG 100% offline como servidor MCP — indexe seus documentos em SQLite (sqlite-vec + FTS5, busca híbrida RRF, embeddings locais via Ollama) e pesquise-os a partir do Claude. Seus documentos nunca saem da sua máquina.

Por quê

  • Um único arquivo SQLite é o índice inteiro — sem serviços externos; backup com cp.

  • Busca híbrida: KNN vetorial (sqlite-vec) + BM25 (FTS5), fundidos com Reciprocal Rank Fusion.

  • Embeddings locais via Ollama (nomic-embed-text).

  • Degradação graciosa: sem Ollama, indexação e busca continuam funcionando em modo lexical (FTS5) com aviso explícito — a busca nunca quebra.

Instalação e configuração

Ainda não publicado no PyPI — instale a partir de um clone deste repositório:

git clone https://github.com/giuseppeferretti/sqlite-rag-mcp
cd sqlite-rag-mcp
pip install .
ollama pull nomic-embed-text   # opcional — busca lexical funciona sem

No Claude Code / Claude Desktop:

{
  "mcpServers": {
    "sqlite-rag": { "command": "sqlite-rag-mcp" }
  }
}

Banco em ~/.local/share/sqlite-rag-mcp/index.db por padrão (configurável via SQLITE_RAG_DB).

Ferramentas

  • index_documents(path, glob) — indexa arquivos texto/markdown de um diretório (arquivos inalterados são pulados).

  • search(query, k, mode) — hybrid (padrão), semantic ou lexical; com Ollama offline, cai para lexical com aviso.

  • get_chunk(chunk_id) — texto completo de um trecho.

  • stats() — contagens e estado do índice.

CLI: python -m sqlite_rag_mcp.index <dir> --glob "**/*.md".

Origem

Núcleo de busca extraído e generalizado de um sistema RAG em produção que responde perguntas sobre o corpus documental de uma empresa — totalmente offline. Case em portfolio.iterlabs.com.br.


Built with AI-assisted development; designed, verified, and operated by Giuseppe Ferretti.

Available Tools

4 tools
get_chunkA

Fetch the full text and source of a chunk returned by search.

Inputs: chunk_id (required). Returns: object

index_documentsA

Index text/markdown files from a directory into the local SQLite index.

Args: path: Directory to index (absolute or ~-expanded). glob: Glob pattern relative to the directory (default '/*.md'). Use e.g. '/.txt' or '**/' for other text files.

Inputs: path (required), glob. Returns: object

statsB

Index statistics: document/chunk/embedding counts and configuration.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a unique, clearly distinct purpose: indexing documents, searching, fetching chunk details, and statistics. No overlap or ambiguity.

    Naming Consistency4/5

    Most names follow a verb_noun pattern (get_chunk, index_documents), but 'search' and 'stats' are single words without an object, introducing minor inconsistency.

    Tool Count5/5

    4 tools is appropriate for a focused RAG server: indexing, querying with retrieval, chunk access, and monitoring. Each tool serves a necessary role.

    Completeness4/5

    Covers the core RAG workflow (index, search, retrieve). Missing a delete or clear index function, but not a major gap for typical usage.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Local-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.
      3
      6 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local MCP server that indexes folders of documents into a hybrid vector + keyword search index for Claude Desktop, with support for PDFs, Office files, and images via OCR.
      MIT