# shinpr/mcp-local-rag [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/shinpr/mcp-local-rag  
**GitHub Stars:** 425  
**npm Downloads (last month):** 10219  
**Views:** 14  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shinpr-mcp-local-rag

## Description
Privacy-first document search server running entirely locally. Supports semantic search over PDFs, DOCX, TXT, and Markdown files with LanceDB vector storage and local embeddings - no API keys or cloud services required.

## Tools
Capabilities this server exposes over MCP:

- **sync_start** — Reconcile the index with all configured roots or one path
- **sync_status** — Poll a running sync job
- **ingest_file** — Ingest or replace one file
- **ingest_data** — Ingest text, Markdown, or HTML already held by the client
- **query_documents** — Search with semantic matching and keyword boost
- **read_chunk_neighbors** — Read surrounding chunks from a search result
- **list_files** — Show supported files and their ingestion state
- **delete_file** — Delete an indexed file or an `ingest_data` item
- **status** — Show index and search status

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-local-rag": {
    "command": "npx",
    "args": ["-y","mcp-local-rag"],
    "env": {
      "BASE_DIR": "",
      "BASE_DIRS": "",
      "IGNORE_PATHS": "",
      "DB_PATH": "",
      "CACHE_DIR": "",
      "HF_ENDPOINT": ""
    }
  }
}
```

**Requires environment variables:** `BASE_DIR`, `BASE_DIRS`, `IGNORE_PATHS`, `DB_PATH`, `CACHE_DIR`, `HF_ENDPOINT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What shinpr/mcp-local-rag does

It combines semantic similarity with keyword matching, which helps queries find both conceptually related passages and exact terms such as API names, class names, or error codes. Search results include source passages and may include headings, line numbers, or page numbers for checking the original material.

The index uses LanceDB for vector storage and a locally cached embedding model. After the initial model download, ingestion and searching can run offline. No API key, Docker installation, Python runtime, or external database is needed.

## How it works

Configure one document root with `BASE_DIR`, or multiple roots with `BASE_DIRS`. A synchronization operation compares the configured files with the index, skips unchanged files, and removes entries for files that have been deleted. You can also ingest or replace one file directly, or pass text, Markdown, or already-fetched HTML through `ingest_data` with a stable source identifier.

MCP paths must be absolute and remain inside a configured document root. When a document changes, run synchronization or ingest that file again. Search can be followed by a neighboring-chunk request to inspect more context around a returned result. The command-line interface provides equivalent operations for ingestion, synchronization, querying, listing, status checks, and deletion.

The first use downloads the default embedding model, which is about 90 MB and requires internet access. Subsequent runs use the local model cache. The server can be started through an MCP client's standard command configuration with `npx -y mcp-local-rag`, or used directly from the terminal with the package's CLI.

## Setup and configuration

Node.js 22.20 or newer is required. Set `BASE_DIR` to an absolute directory containing the documents to index. `BASE_DIRS` accepts a JSON array of roots and takes precedence over `BASE_DIR`; `IGNORE_PATHS` accepts JSON glob patterns for excluding files. Set `DB_PATH` to choose the LanceDB location and `CACHE_DIR` to choose the embedding-model cache. Absolute paths are recommended for both so separate working directories do not create different indexes unintentionally.

Register the package with an MCP client, restart that client, and request a full synchronization. Claude Code, Codex, and Cursor configurations are shown using the `npx` command. The CLI defaults to the current directory as its document root, so ingestion and querying should use the same working directory unless paths are configured explicitly.

## Tools and capabilities

- `sync_start` reconciles all configured roots or a selected path.
- `sync_status` reports progress for an active synchronization job.
- `ingest_file` adds or replaces one supported file.
- `ingest_data` indexes client-held text, Markdown, or HTML.
- `query_documents` performs semantic search with keyword boosting.
- `read_chunk_neighbors` returns surrounding chunks for a search result.
- `list_files` shows supported files and their ingestion state.
- `delete_file` removes an indexed file or an item created with `ingest_data`.
- `status` reports index and search state.

## Limitations and notes

File ingestion does not support Excel, PowerPoint, standalone images, or source-code extensions. HTML retrieval is outside the server: an MCP client must fetch the page and submit its HTML. PDF figures can optionally be described with a local vision model, but this feature is not OCR or image search. PDF section headings may be inaccurate, so consult the original page when exact headings matter.

Keep the database and model cache paths consistent between MCP and CLI usage. When moving a project, stop other database writers, move the files and database without changing their relative layout, relocate the index, update the configured paths, and restart the client.

_Full upstream README: https://allmcps.com/mcp/shinpr-mcp-local-rag/readme_