MCP SERVER · OFFICIAL PROJECTIndex PDF, DOCX, TXT and Markdown files from directories you nominate into a local vector database, search them with hybrid keyword and semantic matching, and read the chunks either side of a hit.
LABSCO SUMMARY
The index is built under directories you nominate and the sync pass keeps it level with what is on disk, so a folder you already maintain stays searchable without being re-added file by file. Reading the neighbouring chunks matters more than it sounds: a single retrieved chunk is often too little to answer from.
A retrieval server over an index held on your own machine. Parsing, embedding, storage and search all run locally, so the documents never reach an embedding API — after the model downloads once, it works offline.
Node.js 22 or later, and BASE_DIR pointing at the directory holding your documents — that directory is also the boundary for file operations, and anything you ingest by path must be given absolutely. No API key, no Docker, no Python and no external database; internet access is needed once, to fetch the package and the embedding model. Changing the embedding model or its quantization changes the embedding space, so re-ingest what is already indexed. MIT.
One command — npx -y mcp-local-rag
USE CASES
Ingest the folder, then query it — the parsing, embedding and search all happen on the machine.
Hybrid matching means an error code or class name is found by the keyword side even when the phrasing around it differs.
Run the sync, then poll the job — new and changed files are ingested, deleted ones are pruned, and the rest are left alone.
Ingest the text under a source identifier, and re-ingest the same identifier when it changes.
Read the document and chunk counts and whether full-text search is on, before blaming the query.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
delete_fileDelete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided. Returns deleted (operation succeeded), removedChunks, and existed (whether anything was actually present).
ingest_dataIngest in-memory content as a string (use ingest_file for files on disk). The source identifier enables re-ingestion to update existing content. Returns { filePath, chunkCount, timestamp, fileTitle }.
ingest_fileIngest a document file (PDF, DOCX, TXT, MD) into the vector database. Path must be absolute; re-ingesting the same path replaces its existing data. Returns { filePath, chunkCount, timestamp, fileTitle }.
list_filesList supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested. Returns { baseDirs, files, sources }; sources lists ingested items reported apart from the file scan, chiefly ingest_data content (web pages, clipboard, etc.).
query_documentsSearch ingested documents with hybrid keyword + semantic matching. Returns results sorted by relevance, each with filePath, chunkIndex, text, fileTitle, score (0 = best, higher = worse), and source (for ingest_data items).
read_chunk_neighborsRead the chunks immediately before and after a query_documents result, in the same document, for more surrounding context. Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data). Returns the target chunk (isTarget: true) and its neighbors, ascending by chunkIndex; an out-of-range chunkIndex returns []. Defaults: before=2, after=2 (max 50 each).
statusGet index status: { documentCount, chunkCount, memoryUsage (MB), uptime (s), ftsIndexEnabled, searchMode }.
sync_startReconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone. Returns { jobId } without waiting for the run to finish; poll sync_status with that jobId for progress and the final outcome. Only one job is kept, and it is lost when the server process exits.
sync_statusGet the current or latest sync job record: { jobId, state ("running" | "succeeded" | "failed"), total (null until scanning has counted the files on disk), completed (upserted + skipped + empty; pruned is counted separately), summary { upserted, skipped, empty, pruned }, warnings, error (null unless the job failed) }. An unknown jobId means the job was replaced by a newer one or lost with a previous server process.
BEFORE YOU INSTALL
9 tools when we connected. STORE_IMAGES, visual and visualQuality change what tools return, not how many. CLI commands such as ingest, sync and skills install are shell subcommands, not tools.
All 4 documented clients run the server on your machine.
CONTEXT COST
Rated by the size of the 9 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx -y mcp-local-ragclaude mcp add local-rag --scope user --env BASE_DIR=<YOUR_BASE_DIR> -- npx -y mcp-local-rag[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]
[mcp_servers.local-rag.env]
BASE_DIR = "<YOUR_BASE_DIR>"{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"local-rag": {
"type": "local",
"command": [
"npx",
"-y",
"mcp-local-rag"
],
"environment": {
"BASE_DIR": "<YOUR_BASE_DIR>"
}
}
}
}{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": [
"-y",
"mcp-local-rag"
],
"env": {
"BASE_DIR": "<YOUR_BASE_DIR>"
}
}
}
}MCP servers
lyonzin
tomohiro-owada
andrea9293
suwa-sh