Skip to content
Back to search

mcp-local-rag

Local-first RAG server for developers. Semantic + keyword search for code and technical docs. Works with MCP or CLI. Fully private, zero setup.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/shinpr/mcp-local-rag with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/shinpr/mcp-local-rag'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shinpr--mcp-local-rag/badge.svg)](/listings/shinpr--mcp-local-rag)

HTML

<a href="/listings/shinpr--mcp-local-rag"><img src="/api/listings/shinpr--mcp-local-rag/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements

- Node.js 22 or later - Internet access on first use to download the npm package and embedding model - A directory containing the documents you want to search

Set `BASE_DIR` to that directory. It is also the security boundary for file operations. Replace `/absolute/path/to/your/documents` below with the directory's absolute path.

Use one of the examples below, or register `npx -y mcp-local-rag` and set `BASE_DIR` using your client's MCP configuration format.

Set `DB_PATH` and `CACHE_DIR` to absolute paths as well. Relative paths resolve from the server's working directory, so starting the server from different projects creates a separate index and model cache in each.

<details> <summary>Claude Code</summary>

Run this command:

claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag

</details>

<details> <summary>Codex</summary>

Add to `~/.codex/config.toml`:

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"

</details>

<details> <summary>OpenCode</summary>

Add to `~/.config/opencode/opencode.json` (or `opencode.jsonc`):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-rag": {
      "type": "local",
      "command": ["npx", "-y", "mcp-local-rag"],
      "environment": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

</details>

<details> <summary>Cursor</summary>

Add to `~/.cursor/mcp.json`:

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

</details>

Restart the client, then ask it to build the index:

Sync all documents in the configured root and wait until it finishes.

The first sync downloads the default embedding model (about 90 MB) and may take 1–2 minutes before ingestion starts. Later runs use the local cache.

Once the sync completes:

What does the API documentation say about authentication?

CLI Quick Start

To use the CLI without an MCP client:

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"

The CLI uses the current directory as its document root by default. Run both commands from the same directory so they use the same default index, or set `BASE_DIR` and `DB_PATH` explicitly.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 471 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/banner.jpg" alt="MCP Local RAG: Search below the surface." width="600" />
  3. </p>
  4. # MCP Local RAG
  5. [![GitHub
  6. stars](https://img.shields.io/github/stars/shinpr/mcp-local-rag?style=social)](https://github.com/shinpr/mcp-local-rag)
  7. [![npm
  8. version](https://img.shields.io/npm/v/mcp-local-rag.svg)](https://www.npmjs.com/package/mcp-local-rag)
  9. [![License:
  10. MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  11. [![MCP
  12. Registry](https://img.shields.io/badge/MCP-Registry-green.svg)](https://registry.modelcontextprotocol.io/)
  13. <p align="center">
  14. <strong>English</strong> |
  15. <a href="README.zh-CN.md">简体中文</a> |
  16. <a href="README.de.md">Deutsch</a> |
  17. <a href="README.es.md">Español</a> |
  18. <a href="README.pt-BR.md">Português (Brasil)</a> |
  19. <a href="README.fr.md">Français</a>
  20. </p>
  21. Search private documents from an MCP client or the terminal without sending them to an
  22. embedding API.
  23. mcp-local-rag indexes PDF, DOCX, Markdown, and text files on your machine. Search combines
  24. semantic similarity with keyword matching, so queries can match both intent and exact technical
  25. terms such as API names, class names, and error codes. Results include source passages and,
  26. where available, headings, line numbers, or page numbers so you can check and cite the original
  27. document.
  28. No API key, Docker, Python, or external database is required. After the initial model download,
  29. text ingestion and search work offline.
  30. ## Quick Start
  31. ### Requirements
  32. - Node.js 22.20 or later
  33. - Internet access on first use to download the npm package and embedding model
  34. - A directory containing the documents you want to search
  35. Set `BASE_DIR` to that directory. It is also the security boundary for file operations. Replace
  36. `/absolute/path/to/your/documents` below with the directory's absolute path.
  37. Use one of the examples below, or register `npx -y mcp-local-rag` and set `BASE_DIR` using your
  38. client's MCP configuration format.
  39. Set `DB_PATH` and `CACHE_DIR` to absolute paths as well. Relative paths resolve from the
  40. server's working directory, so starting the server from different projects creates a separate
  41. index and model cache in each.
  42. <details>
  43. <summary>Claude Code</summary>
  44. Run this command:
  45. ```bash
  46. claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag
  47. ```
  48. </details>
  49. <details>
  50. <summary>Codex</summary>
  51. Add to `~/.codex/config.toml`:
  52. ```toml
  53. [mcp_servers.local-rag]
  54. command = "npx"
  55. args = ["-y", "mcp-local-rag"]
  56. [mcp_servers.local-rag.env]
  57. BASE_DIR = "/absolute/path/to/your/documents"
  58. ```
  59. </details>
  60. <details>
  61. <summary>OpenCode</summary>
  62. Add to `~/.config/opencode/opencode.json` (or `opencode.jsonc`):
  63. ```json
  64. {
  65. "$schema": "https://opencode.ai/config.json",
  66. "mcp": {
  67. "local-rag": {
  68. "type": "local",
  69. "command": ["npx", "-y", "mcp-local-rag"],
  70. "environment": {
  71. "BASE_DIR": "/absolute/path/to/your/documents"
  72. }
  73. }
  74. }
  75. }
  76. ```
  77. </details>
  78. <details>
  79. <summary>Cursor</summary>
  80. Add to `~/.cursor/mcp.json`:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "local-rag": {
  85. "command": "npx",
  86. "args": ["-y", "mcp-local-rag"],
  87. "env": {
  88. "BASE_DIR": "/absolute/path/to/your/documents"
  89. }
  90. }
  91. }
  92. }
  93. ```
  94. </details>
  95. Restart the client, then ask it to build the index:
  96. ```text
  97. Sync all documents in the configured root and wait until it finishes.
  98. ```
  99. The first sync downloads the default embedding model (about 90 MB) and may take 1–2 minutes
  100. before ingestion starts. Later runs use the local cache.
  101. Once the sync completes:
  102. ```text
  103. What does the API documentation say about authentication?
  104. ```
  105. ### CLI Quick Start
  106. To use the CLI without an MCP client:
  107. ```bash
  108. npx mcp-local-rag ingest ./docs/
  109. npx mcp-local-rag query "authentication API"
  110. ```
  111. The CLI uses the current directory as its document root by default. Run both commands from the
  112. same directory so they use the same default index, or set `BASE_DIR` and `DB_PATH` explicitly.
  113. ## Supported Content
  114. | Input | How to ingest |
  115. |---|---|
  116. | PDF, DOCX, TXT, Markdown | File ingestion or directory sync |
  117. | HTML already fetched by the client | `ingest_data` |
  118. | Plain text or Markdown held in memory | `ingest_data` with a stable source identifier |
  119. HTML fetching is not built into the server. An MCP client can fetch a page and pass its HTML to
  120. `ingest_data`.
  121. Excel, PowerPoint, standalone images, and source-code file extensions are not supported by file
  122. ingestion. PDFs can optionally use a local vision model to describe figures, but this is not
  123. OCR or image search.
  124. ## Using the Index
  125. Sync after adding, editing, or removing documents. For searches and follow-up reading, ask your
  126. MCP client:
  127. ```text
  128. Find the documented behavior of ERR_CONNECTION_REFUSED.
  129. Read the surrounding chunks for that result.
  130. ```
  131. You can also ingest a single file or HTML already fetched by the client. To refresh an existing
  132. entry, ingest the document again using the same path or source identifier. `sync` skips unchanged
  133. files. MCP file paths must be absolute and inside a configured document root.
  134. PDF section headings may be inaccurate. Check the original page when you need the exact heading.
  135. <details>
  136. <summary>MCP Tools</summary>
  137. | Tool | Purpose |
  138. |---|---|
  139. | `sync_start` | Reconcile the index with all configured roots or one path |
  140. | `sync_status` | Poll a running sync job |
  141. | `ingest_file` | Ingest or replace one file |
  142. | `ingest_data` | Ingest text, Markdown, or HTML already held by the client |
  143. | `query_documents` | Search with semantic matching and keyword boost |
  144. | `read_chunk_neighbors` | Read surrounding chunks from a search result |
  145. | `list_files` | Show supported files and their ingestion state |
  146. | `delete_file` | Delete an indexed file or an `ingest_data` item |
  147. | `status` | Show index and search status |
  148. </details>
  149. ## CLI
  150. Use the CLI to update the index, narrow searches, or remove indexed content:
  151. ```bash
  152. npx mcp-local-rag sync ./docs/
  153. npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
  154. npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
  155. npx mcp-local-rag list
  156. npx mcp-local-rag status
  157. npx mcp-local-rag delete ./docs/old.pdf
  158. npx mcp-local-rag delete --source "https://example.com/docs"
  159. ```
  160. `ingest` imports the selected files; `sync` also removes entries for deleted files and skips
  161. unchanged files. Use `--scope` to restrict search results to a path prefix, repeating it to
  162. include multiple prefixes.
  163. Global options such as `--db-path`, `--cache-dir`, and `--model-name` go before the subcommand.
  164. Subcommand options go after it:
  165. ```bash
  166. npx mcp-local-rag --db-path ./my-db query "authentication"
  167. ```
  168. Run `npx mcp-local-rag --help` for the complete command reference.
  169. `query` writes its results to stdout as JSON, best match first, so it can be piped into another
  170. tool. The field-by-field contract is in
  171. [`docs/schema/query-output.schema.json`](docs/schema/query-output.schema.json).
  172. If you move a project and want to keep its index, stop the MCP server and other database
  173. writers, move the files and database together without changing the directory layout, then run:
  174. ```bash
  175. npx mcp-local-rag --db-path /new/project/lancedb relocate --from /old/project --to /new/project
  176. ```
  177. Update `BASE_DIR`/`BASE_DIRS`, `DB_PATH`, and any other moved paths in your MCP configuration,
  178. then restart the client.
  179. ## Agent Skills
  180. [Agent Skills](https://agentskills.io/) provide query and ingestion guidance for AI assistants:
  181. ```bash
  182. npx mcp-local-rag skills install --claude-code
  183. npx mcp-local-rag skills install --claude-code --global
  184. npx mcp-local-rag skills install --codex
  185. ```
  186. Installed skills cover query formulation, result refinement, and HTML ingestion. Ask the
  187. assistant to use the mcp-local-rag skill explicitly if it does not activate automatically.
  188. ## Advanced Options
  189. Start with the defaults. Open the sections below when you need different document roots, better
  190. results for your corpus, or searchable PDF figures.
  191. <details>
  192. <summary>Storage and Document Roots</summary>
  193. The MCP server reads environment variables. The CLI accepts the listed variables and flags.
  194. Keep the same `DB_PATH` when commands should use the same index.
  195. | Environment Variable | CLI Flag | Default | Description |
  196. |---------------------|----------|---------|-------------|
  197. | `BASE_DIR` | `--base-dir` | Current directory | One document root; the CLI flag is repeatable on `ingest`, `list`, and `sync` |
  198. | `BASE_DIRS` | N/A | (unset) | JSON array of document roots; takes precedence over `BASE_DIR` |
  199. | `IGNORE_PATHS` | N/A | (unset) | JSON array of glob patterns for files to keep out of the index |
  200. | `DB_PATH` | `--db-path` | `./lancedb/` | Vector database location |
  201. | `CACHE_DIR` | `--cache-dir` | `./models/` | Model cache directory |
  202. | `HF_ENDPOINT` | N/A | `https://huggingface.co` | Hugging Face model download endpoint; use a mirror URL when direct downloads are blocked |
  203. | `MAX_FILE_SIZE` | `--max-file-size` | `104857600` (100MB) | Maximum file size in bytes |
  204. File operations stay within configured roots. For multiple directories, set
  205. `BASE_DIRS='["/absolute/docs","/absolute/specs"]'` or repeat CLI `--base-dir`. Precedence: CLI
  206. roots, `BASE_DIRS`, `BASE_DIR`, then the current directory. Only the highest-priority source is
  207. used; roots from different sources are not merged. Invalid `BASE_DIRS` is an error. Relative
  208. `DB_PATH` and `CACHE_DIR` are resolved from the working directory.
  209. To keep files out of the index, set `IGNORE_PATHS` to a JSON array of glob patterns, for example
  210. `IGNORE_PATHS='["plugs/**","**/*.draft.md"]'`. Each pattern is matched against the file's path
  211. relative to the root that contains it, written with `/` on every OS. `ingest`, `list`, and `sync`
  212. skip matching files when they scan a directory, and `sync` removes any that are already indexed.
  213. Invalid `IGNORE_PATHS` is an error.
  214. </details>
  215. <details>
  216. <summary>Models and Search Tuning</summary>
  217. Choose an embedding model for your documents’ language and subject. Compare settings using
  218. questions you actually ask and check which source passages are returned. The model must support
  219. mean pooling and L2 normalization, which this tool uses to produce embeddings.
  220. | Environment Variable | CLI Flag | Default | Description |
  221. |---------------------|----------|---------|-------------|
  222. | `MODEL_NAME` | `--model-name` | `Xenova/all-MiniLM-L6-v2` | Hugging Face embedding model |
  223. | `CHUNK_MIN_LENGTH` | `--chunk-min-length` | `50` | Minimum length in characters (1–10000) for ordinary chunks; a fragment of content split to fit the model's token limit can be shorter |
  224. | `EMBED_TITLE_PREFIX` | N/A | `false` | Add the document title to each chunk's embedding input |
  225. | `EMBED_HEADING_PREFIX` | N/A | `false` | Add the heading hierarchy to each chunk's embedding input when it fits |
  226. | `RAG_DEVICE` | N/A | `cpu` | ONNX Runtime execution device |
  227. | `RAG_DTYPE` | N/A | `fp32` | Embedding dtype passed to the selected model |
  228. Both prefix options default to `false` and work independently. Try `EMBED_TITLE_PREFIX` when a
  229. passage needs the document’s overall topic, or `EMBED_HEADING_PREFIX` when it needs its
  230. section’s topic. Enabling both is not always better. They affect embeddings, not the returned
  231. text or keyword index; heading context is omitted when it would exceed the input budget.
  232. When changing embedding models, build a fresh index at a new `DB_PATH`. Vectors from different
  233. models are not comparable, even when their dimensions match. After changing `RAG_DTYPE` or
  234. either prefix option, re-ingest all indexed documents before searching. `sync` skips unchanged
  235. files.
  236. The CLI does not read MCP client configuration. When sharing an index, use the same model,
  237. `RAG_DTYPE`, and prefix settings for ingestion and search. A change to `RAG_DEVICE` alone does
  238. not require a new index.
  239. ### Search Tuning
  240. The first four settings below apply to both MCP and CLI queries. To give exact terms more
  241. weight, try increasing `RAG_HYBRID_WEIGHT` and compare results on your own questions. External
  242. reranking is MCP-only.
  243. | Variable | Default | Description |
  244. |----------|---------|-------------|
  245. | `RAG_HYBRID_WEIGHT` | `0.6` | Keyword boost factor (0.0–1.0). 0 disables keyword reranking; 1 applies the maximum boost. |
  246. | `RAG_GROUPING` | (not set) | `similar` keeps the first relevance group; `related` keeps up to two, using significant vector-distance gaps as boundaries. |
  247. | `RAG_MAX_DISTANCE` | (not set) | Filter out low-relevance results (e.g., `0.5`). |
  248. | `RAG_MAX_FILES` | (not set) | Limit results to top N files (e.g., `1` for single best file). |
  249. | `RAG_RERANK_CMD` | (not set) | MCP only: external command; `{query}` passes the query and `{top}` the requested result count. |
  250. | `RAG_RERANK_TIMEOUT_MS` | `10000` | Time budget per rerank call in milliseconds (100–600000). |
  251. ### External Reranking (`RAG_RERANK_CMD`)
  252. The command reads search results, including matched text, from stdin. If it calls a remote
  253. service, that text may leave your machine.
  254. Give the executable and its complete argument template. Put `{query}` and `{top}` where the
  255. command expects the query and result count. Single or double quotes group paths or arguments
  256. containing spaces, and backslashes stay literal. The server runs the executable without a
  257. shell, so an npm-installed `.cmd` shim on Windows will not start.
  258. ```json
  259. {
  260. "env": {
  261. "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
  262. "RAG_RERANK_TIMEOUT_MS": "10000"
  263. }
  264. }
  265. ```
  266. The command must read and return results in the format defined by [the query output
  267. schema](docs/schema/query-output.schema.json). It can remove or reorder results and modify
  268. their text. The server returns its output.
  269. Results keep their original order if the command fails, times out, or returns output that does
  270. not match the schema.
  271. </details>
  272. <details>
  273. <summary>PDF Figures and Stored Images</summary>
  274. By default, ingestion indexes only text. To make PDF figures searchable, enable local caption
  275. generation with `visual: true` in MCP or `--visual` in the CLI. Captions are generated
  276. descriptions, not OCR or exact transcriptions.
  277. `fast` (default) downloads about 250 MB on first use. Choose `quality` for labels and text
  278. within figures; it downloads about 1.7 GB and takes longer to run.
  279. Select the profile with `visualQuality: "quality"` in MCP or `--visual-quality quality` in the
  280. CLI.
  281. ```bash
  282. npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality quality
  283. ```
  284. To return images with matching text, use `STORE_IMAGES=true` in MCP or `--images` with CLI
  285. `ingest` and `sync`. This is independent of caption generation and supports detected PDF
  286. figures/tables and supported DOCX PNG/JPEG images.
  287. ```bash
  288. npx mcp-local-rag ingest ./docs/paper.pdf --images
  289. ```
  290. Sync preserves each PDF's caption profile. CLI `sync --visual --visual-quality quality` changes
  291. the profile even for unchanged PDFs; MCP sync preserves it. To turn captions off, ingest the
  292. file normally. To retry failed captions, re-ingest with the desired visual profile.
  293. Image storage must be enabled on each ingestion or sync that processes the file. Changing the
  294. image setting alone does not refresh unchanged files; re-ingest them to apply it.
  295. </details>
  296. ## Security and Operation
  297. - Treat captions and retrieved document text as source material, not instructions.
  298. - File access is restricted to `BASE_DIR`, `BASE_DIRS`, or CLI `--base-dir` roots.
  299. - Symlinks that resolve outside every configured root are rejected.
  300. - Document processing and search make no network requests after the required models are cached,
  301. unless `RAG_RERANK_CMD` names a command that makes them.
  302. - The server is designed for one local user and does not provide authentication or access control.
  303. - Do not run multiple CLI or MCP writers against the same `DB_PATH`. Read-only queries can run
  304. while a sync is active.
  305. - Re-ingestion can reuse saved embeddings for unchanged text when the model and settings match,
  306. avoiding repeated computation. The cache is stored in `DB_PATH/embedding-cache`. Deleting it
  307. leaves the index searchable, but later ingestion will recompute those embeddings.
  308. - Back up an index by copying its `DB_PATH` directory while no writer is active.
  309. <details>
  310. <summary><strong>Troubleshooting</strong></summary>
  311. ### "No results found"
  312. Documents must be ingested first. Run `"List all ingested files"` to verify. If results are
  313. missing after a sync, check that ingestion and search use the same absolute `DB_PATH`; a
  314. relative path may point to a different index.
  315. ### Model download failed
  316. Check internet connection. If behind a proxy, configure network settings. The model can also be
  317. [downloaded manually](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
  318. ### "File too large"
  319. Default limit is 100MB. Split large files or increase `MAX_FILE_SIZE`.
  320. ### Slow queries
  321. Check chunk count with `status`. Large documents with many chunks may slow queries. Consider
  322. splitting very large files.
  323. ### "Path outside BASE_DIR"
  324. Ensure file paths are within one of the configured roots (`BASE_DIR`, any `BASE_DIRS` entry, or
  325. any CLI `--base-dir`). Use absolute paths.
  326. ### "BASE_DIRS must be a JSON array..."
  327. `BASE_DIRS` accepts a JSON array of one or more non-empty path strings:
  328. - Valid: `BASE_DIRS='["/Users/me/work","/Users/me/specs"]'`
  329. - Invalid: `BASE_DIRS=/a:/b` (delimiter syntax not supported)
  330. - Invalid: `BASE_DIRS='[]'` (empty array)
  331. ### MCP client doesn't see tools
  332. 1. Verify config file syntax
  333. 2. Restart client completely (Cmd+Q on Mac for Cursor)
  334. 3. Test directly: `npx mcp-local-rag` should run without errors
  335. </details>
  336. ## Contributing
  337. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
  338. ## License
  339. MIT License. Free for personal and commercial use.
  340. ## Blog Posts
  341. - [Building a Local RAG for Agentic Coding](https://www.norsica.jp/blog/local-rag-agentic-coding): Technical deep-dive into the semantic chunking and hybrid search design.
  342. ## Acknowledgments
  343. Built with [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic,
  344. [LanceDB](https://lancedb.com/), and
  345. [Transformers.js](https://huggingface.co/docs/transformers.js).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.