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

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/shinpr/mcp-local-rag  
**GitHub Stars:** 390  
**npm Downloads (last month):** 15322  
**Views:** 3  
**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": ""
    }
  }
}
```

**Requires environment variables:** `BASE_DIR` — 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 MCP server does

shinpr/mcp-local-rag MCP server creates a local searchable index for PDF, DOCX, TXT, and Markdown files. It can also index plain text, Markdown, or HTML supplied by an MCP client through `ingest_data`. HTML is cleaned and converted to Markdown after the client provides it; fetching web pages is not built into the server.

Search combines semantic similarity with keyword matching. This allows natural-language queries to find related passages while giving additional weight to exact terms such as API names, class names, and error codes. The index uses LanceDB vector storage and local Hugging Face embedding models. After the initial embedding model download, ingestion and search can run offline.

## How it works

Configure one or more document roots and use `sync_start` to reconcile their contents with the index. The sync operation adds new files, replaces changed files, skips byte-identical files, and removes entries for files that no longer exist. It returns a job ID, which clients can pass to `sync_status` until the job succeeds or fails. Only one sync job record is retained by a running server process.

For individual documents, `ingest_file` accepts absolute paths inside a configured root and replaces prior chunks when the same path is ingested again. `ingest_data` stores client-held content under a source identifier; reusing that identifier updates the existing item.

`query_documents` returns matching text with source details, chunk indexes, titles, and relevance scores. When a result needs more context, `read_chunk_neighbors` retrieves surrounding chunks using the result identity. `list_files`, `delete_file`, and `status` provide index and ingestion-state management.

## Setup and configuration

shinpr/mcp-local-rag MCP server requires Node.js 22 or later. Start it with `npx -y mcp-local-rag` and set `BASE_DIR` to an absolute document directory. The configured root also acts as the boundary for file operations. The first use needs internet access to download the npm package and the default embedding model, which is about 90 MB; subsequent runs use the local cache.

The server communicates over local MCP stdio and can be registered with clients that support local MCP servers. The README provides a Cursor configuration using the `npx` command and `BASE_DIR`. A CLI is also available for direct use from a terminal, including `ingest` and `query` commands. The CLI defaults to the current directory, or can use explicit `BASE_DIR` and `DB_PATH` values.

## Tools and capabilities

- `sync_start` and `sync_status` manage asynchronous directory synchronization.
- `ingest_file` adds or replaces a supported local file.
- `ingest_data` indexes text, Markdown, or HTML already held by the client.
- `query_documents` performs hybrid semantic and keyword search.
- `read_chunk_neighbors` retrieves context around a result.
- `list_files`, `delete_file`, and `status` inspect or manage the index.
- Optional PDF visual captions use a local vision model; `STORE_IMAGES=true` enables image storage for supported new or changed files selected by sync.

## Limitations and notes

File ingestion does not support Excel, PowerPoint, standalone images, or source-code file extensions. PDF visual processing is not OCR or image search. DOCX image storage covers PNG and JPEG images emitted by the existing conversion path, not charts, SmartArt, or shapes. Changed files keep the visual profile used when they were indexed, and a later sync cannot change that profile. Sync records are lost when the server restarts.

External HTML must be fetched by the MCP client, and users should follow the source site's terms and copyright requirements when indexing it. No API key, Docker, Python, or external database is required.

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