# 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.

- **URL**: https://www.freshcrate.ai/projects/mcp-local-rag
- **Author**: shinpr
- **Category**: MCP Servers
- **Latest version**: `v0.14.2` (2026-05-23)
- **License**: MIT
- **Source**: https://github.com/shinpr/mcp-local-rag
- **Language**: TypeScript
- **GitHub**: 229 stars, 42 forks
- **Registry**: github
- **Tags**: `agent-skills`, `developer-tools`, `hybrid-search`, `local-first`, `local-rag`, `mcp`, `mcp-server`, `privacy-first`, `typescript`

## Description

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

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v0.14.2` | 2026-05-23 | High | ## Added  - **`BASE_DIRS`** — JSON array env var to configure multiple document roots, e.g. `BASE_DIRS='["/a","/b"]'`. - **Repeatable `--base-dir`** for `ingest` and `list`. CLI roots replace env roots. - Precedence: CLI `--base-dir` > `BASE_DIRS` > `BASE_DIR` > `cwd`.  ## Changed  - Configuration warnings (e.g. `BASE_DIRS is set; BASE_DIR is ignored.`) now appear in MCP tool responses, not only stderr. - `list_files` returns `baseDirs: string[]` and per-file `baseDir`. Legacy `baseDir` |
| `v0.14.0` | 2026-05-17 | High | ## Changes  - **Visual ingest for PDFs (opt-in).** `visual: true` (MCP) or `--visual` (CLI) inlines a short caption from a local VLM (`HuggingFaceTB/SmolVLM-256M-Instruct`) into the text chunks for each page with figures, tables, or diagrams. Captions are auxiliary text — not image search, not OCR, and not a faithful transcription of the figure. Default ingest is unchanged. See the README's *Ingesting PDFs with figures* section for usage and the security note. - **GPU acceleration.** Embeddin |
| `v0.13.2` | 2026-05-11 | High | Patch release improving `read_chunk_neighbors` input validation.  ## Fixes  - `read_chunk_neighbors` now treats an empty or whitespace-only `filePath`/`source` as not provided. Passing `source: ""` alongside a valid `filePath` returns the document window instead of resolving to an empty raw-data path and returning nothing. - The `filePath`/`source` validation error now matches the actual situation: "Provide either filePath or source, not both" when both are given, "Either filePath or source |
| `v0.13.1` | 2026-05-07 | High | Patch release for dependency upgrades.  ## Dependencies  - `@huggingface/transformers` ^4.0.0 → ^4.2.0   - Minor version bump in the embedding library. Embedding output may differ slightly from v0.13.0; re-ingest existing documents if you observe behavior changes. - `@lancedb/lancedb` ^0.26.2 → ^0.27.2 - `@modelcontextprotocol/sdk` ^1.28.0 → ^1.29.0 - `jsdom` ^27.4.0 → ^29.1.1 - `turndown` 7.2.2 → 7.2.4  ## Transitive  - `protobufjs` 7.5.4 → 7.5.5 (#108) - `@xmldom/xmldom` 0.8.11 → |
| `v0.13.0` | 2026-04-17 | High | ## What's New  **New tool: `read_chunk_neighbors`** — Expand a search result by reading the chunks immediately before and after it in the same document.  After finding a relevant chunk via `query_documents`, pass its `chunkIndex` and `filePath` (or `source`) to retrieve surrounding context in a single call. Useful when a hit answers a question only partially.  ### MCP Tool  ``` read_chunk_neighbors({ filePath: "/path/to/doc.md", chunkIndex: 5 }) ```  ### CLI  ```bash npx mcp-local |
| `v0.12.0` | 2026-04-02 | Medium | ## Added  - `CHUNK_MIN_LENGTH` environment variable and `--chunk-min-length` CLI flag to configure minimum chunk length in characters (range: 1–10,000, default: 50) - `CHUNK_MIN_LENGTH` entry in MCP server manifest (`server.json`)  ## Changed  - Minimum chunk length default (50) is now exported as a single source of truth from the chunker module - Error message for zero-chunk ingestion now reflects the actual configured value instead of hardcoded "50" - Warning and error messages across |
| `v0.11.1` | 2026-03-30 | Medium | ## Security  - Upgrade `@huggingface/transformers` from v3 to v4 (#97)   - Resolves 3 high-severity `tar` CVEs (GHSA-34x7, GHSA-8qq5, GHSA-83g3) - Replace `madge` with `dpdm` for circular dependency checking (#97)   - Resolves `minimatch` ReDoS vulnerabilities  ## Internal  - Add `pnpm-workspace.yaml` with `allowBuilds` for pnpm v10 build script security |
| `v0.11.0` | 2026-03-30 | Medium | ## Breaking changes  - Minimum Node.js version raised from 20 to 22 (#96)   - Node.js 20 reaches EOL on April 30, 2026  ## Internal  - TypeScript target updated from ES2020 to ES2023 |
| `v0.10.1` | 2026-03-29 | Medium | ## Bug fixes  - Reject non-numeric values for `--max-file-size` and `--limit` CLI flags (#92)  ## Security  - Update `@modelcontextprotocol/sdk` 1.27.1 → 1.28.0 - Update `mammoth` 1.11.0 → 1.12.0 - Update `vitest` 4.0.18 → 4.1.2 (resolves `rollup` vulnerability) - Update `knip` 5.88.0 → 6.1.0 (resolves `picomatch` vulnerability) |
| `v0.10.0` | 2026-03-19 | Low | ## Full CLI support — all MCP tools now available as CLI commands  mcp-local-rag can now be used entirely without an MCP server. All six MCP tools have CLI equivalents:  ```bash npx mcp-local-rag ingest ./docs/           # Bulk ingest files npx mcp-local-rag query "search text"      # Search documents npx mcp-local-rag list                     # Show ingestion status npx mcp-local-rag status                   # Database stats npx mcp-local-rag delete ./docs/old.pdf    # Remove by file p |

## Citation

- HTML: https://www.freshcrate.ai/projects/mcp-local-rag
- Markdown: https://www.freshcrate.ai/projects/mcp-local-rag.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/mcp-local-rag/deps

_Generated by freshcrate.ai. Indexes github releases for AI-agent ecosystem packages._