sqlite-rag-mcp
Provides local embedding generation for semantic search via Ollama (nomic-embed-text by default), with graceful fallback to lexical search if Ollama is unavailable.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sqlite-rag-mcp search for how to rotate API tokens"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-textby 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| FInstall
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 itConfigure 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-mcpEnvironment variable | Default | Purpose |
|
| Index database path |
|
| Ollama endpoint |
|
| Embedding model |
|
| Chunk size (approx. tokens) |
|
| 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.dbHow search works
The query is embedded locally (Ollama) and run against the
vec0KNN index; in parallel a sanitized, OR-expanded prefix query runs against FTS5 (BM25).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.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 clientRelated 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 semNo 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),semanticoulexical; com Ollama offline, cai paralexicalcom 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 toolsget_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
searchA
Search the indexed documents.
Args: query: Natural-language query or keywords. k: Number of results to return (1-50, default 8). mode: 'hybrid' (RRF fusion of semantic + lexical, default), 'semantic' (vector KNN only), or 'lexical' (FTS5 BM25 only). If Ollama is offline, hybrid/semantic fall back to lexical and a warning is included in the response.
Inputs: query (required), k, mode. 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
Scored across 4 tools
Each tool has a unique, clearly distinct purpose: indexing documents, searching, fetching chunk details, and statistics. No overlap or ambiguity.
Most names follow a verb_noun pattern (get_chunk, index_documents), but 'search' and 'stats' are single words without an object, introducing minor inconsistency.
4 tools is appropriate for a focused RAG server: indexing, querying with retrieval, chunk access, and monitoring. Each tool serves a necessary role.
Covers the core RAG workflow (index, search, retrieve). Missing a delete or clear index function, but not a major gap for typical usage.
Maintenance
Related MCP Connectors
An MCP server for search and retrieval over a local LanceDB database
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.36 npmMIT
- AlicenseNot gradedqualityDmaintenanceLocal MCP server for indexing personal knowledge into SQLite with hybrid search, chunk-level citations, memory tools, and agent orchestration.4MIT
- AlicenseNot gradedqualityDmaintenanceLocal 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
- FlicenseNot gradedqualityDmaintenanceMCP server enabling Claude Desktop to answer questions from local Word and PDF documents by searching a vector index built from their contents.-