# Reported issues for mcp-local-rag

Pod holds 19 of 22 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [mcp-local-rag](/mcp/mcp-local-rag).

## Most discussed

### Feature request: page screenshot

Hi!

I've noticed that my model quite often tries to render the pdf directly after retrieving the query results. Probably it was looking for diagrams or table layouts. I think it could be quite useful to provide a tool that returns an image of a page (by page number or by chunk index) as an [MCP image content](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#image-content), i.e.:

```json
{
  "content": [
    {
      "type": "text",
      "text": "iVBORw0KGgoAAAANSUhEUgAA...

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/189) · 2026-08-20 · closed · external user · 3 comments

### Startup speed

I am not sure if it's actually a `mcp-local-rag` issue, but I am experiencing a slow startup speed with codex.
It takes me 15-22 seconds (inconsistent) to initialize the MCP server. The CLI `npx mcp-local-rag status` takes about 5 seconds. And the same mcp-local-rag mcp server wrapped as HTTP server with `supergateway` takes about 10 seconds (consistently) to initialize.
How can I debug it?

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/184) · 2026-08-10 · closed · external user · 2 comments

### Feature request: optional filter on list_files

Hi. I’m testing `mcp-local-rag` on a volume containing several thousand files. I’m using the Zed editor with a custom MCP setup and OpenAI.

The `list_files` tool runs into a timeout when trying to find files with a specific name or when opening a specific directory.

This appears to be related to: https://github.com/shinpr/mcp-local-rag/issues/146

There should be a filter or scope option to limit the result set.

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/165) · 2026-07-08 · closed · external user · 4 comments

### Feature request: optional scope filter on query_documents to search one corpus in a shared database

**What I'm asking for**

An optional `scope` parameter on `query_documents` (and the `query` CLI) that limits a search to documents under one or more path prefixes. Today one database mixes every ingested corpus, and a query cannot target just one.

**Why it matters**

I run several corpora through one server: meeting transcripts, separate research studies, general docs. With a shared `DB_PATH`, every query ranks across all of them, so a chunk from an unrelated corpus can sit close to my query i

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/146) · 2026-06-11 · closed · external user · 2 comments

### Feature Request: Support Incremental Synchronization

## Current Behavior
Currently, updating the document index requires a full re-ingestion of the target directory. 

## Desired Behavior
Add support for incremental updates. The index should be able to synchronize with the filesystem by:
1. Detecting changes (modifications) to existing files.
2. Identifying new files.
3. Detecting and removing (pruning) files that have been deleted from disk.

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/121) · 2026-05-12 · closed · outside contributor · 2 comments

### FTS index rebuild after every ingest makes bulk ingestion O(n²)

## Problem

`rebuildFtsIndex()` calls `table.optimize()` after every `insertChunks()` and `deleteChunks()`. For a single file this is fine, but when ingesting many files sequentially (e.g. 978 small markdown files), each `ingest_file` call triggers two `optimize()` calls (one for delete, one for insert), and each gets progressively slower as the table grows.

The result is that bulk ingestion of ~1,000 small files (~12KB each, 12MB total) takes far longer than the embedding work alone would sugg

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/75) · 2026-03-17 · closed · external user · 2 comments

### HTTP Streaming MCP Server?

Would you be open to a PR that contains a HTTP Streamable MCP server out of interest? The intention is for it to only run locally but be available for multiple clients to use a central RAG database rather than having repeated local versions. It would be HTTP only and use a static bearer token for simple authentication. The default operation would still be stdio but have the option to enable http through env variables.

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/64) · 2026-02-25 · closed · outside contributor · 3 comments

### Logs to stdout

Hello, 

It looks like logs are directed to stdout which confuses the MCP client (Claude Desktop in my case).  Am I doing something wrong?

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/12) · 2025-12-05 · closed · external user · 2 comments

## Most recent

### Question about the `sync` command in the CLI

I'm using multiple databases with mcp-local-rag.
I successfully created and populated a database using the ingest command with --base-dir.
Later, I tried to update the same database using the sync command, but sync returned the following error.
Is there a way to specify the base directory when running sync from the CLI?
If not, what is the recommended workflow for updating an existing database created with ingest --base-dir?

- Successful ingest command
  - npx mcp-local-rag --db-path "D:\mcp_ra

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/185) · 2026-08-11 · closed · external user · 1 comment

### ingest_file effectively hangs on documents with a long unbroken line (batch padding amplifies an untruncated ~3.5k-token sentence)

## Summary

`ingest_file` effectively never completes (silent, runaway memory) on markdown/text documents that contain a single long unbroken line with no sentence punctuation — e.g. a comma-separated list of API resource paths, a long URL list, or minified data. The server logs `Parsed MD: ...` and then goes quiet while the process spins at high CPU with RSS climbing past 3GB. In production this repeatedly ate entire 60-minute ingest runs; in a controlled test the stuck batch was killed at 180s

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/178) · 2026-07-28 · closed · external user · 1 comment

### Feature Request: --chunk-size, or support for models like bge-large-zh-1.5?

I often encounter errors when using models like bge-large-zh-1.5 or gte-large, like this:

```
[MCP Server] 26-05-28 02:26:07.0061665 [E:onnxruntime:, sequential_executor.cc:572 onnxruntime::ExecuteK
[MCP Server] ernel] Non-zero status code returned while running Add node. Name:'/embeddin
[MCP Server] gs/Add_1' Status Message: E:\_work\1\s\onnxruntime\core/providers/cpu/math/e
[MCP Server] lement_wise_ops.h:560 onnxruntime::BroadcastIterator::Append axis == 1 || a
[MCP Server] xis == largest was

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/142) · 2026-05-27 · closed · external user · 2 comments

### Feature request: Support multiple BASE_DIR roots for local document search

# Support multiple BASE_DIR roots for local document search

## Feature request

Support configuring more than one document root for `mcp-local-rag`, while preserving the current path-safety guarantees of `BASE_DIR`.

## Problem

Today, `BASE_DIR` appears to be a single document root. This works well when all searchable documents live under one parent directory, but it is awkward when a user has documents split across multiple unrelated directories, for example:

- `~/Documents/work`
- `~/Docume

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/139) · 2026-05-22 · closed · external user · 1 comment

### feat: incremental sync_data with non-blocking progress notifications

## Feature

Add a `sync_data` MCP tool and `sync` CLI subcommand for incremental synchronisation of a directory against the vector DB.

## Motivation

Currently ingesting a large directory re-embeds everything from scratch on every run. An incremental sync should diff disk state against DB state (using content hashes), only re-embed changed files, and prune deleted files — making repeated syncs fast.

Additionally, the current `ingest` flow blocks until complete. For large directories this gives

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/129) · 2026-05-14 · closed · outside contributor · 1 comment

### Feature request: GPU support

## Feature

Enable GPU acceleration for embedding generation.

## Motivation

My CPU fan is noisy.

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/127) · 2026-05-14 · closed · outside contributor · 0 comments

### feat: zero-build npx execution support

## Feature

Allow the package to run directly from source via `npx` without requiring a prior build step.

Currently the `bin` entry points to `dist/index.js`, so users must run `pnpm build` before `npx mcp-local-rag` works. A thin wrapper script would let npx invoke `tsx` directly on the source.

## Additional benefit

`npx`/`npm` set `INIT_CWD` to the original working directory, but `process.cwd()` can point to the npx cache. Without correcting for this, relative paths like `./lancedb/` resolv

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/125) · 2026-05-14 · closed · outside contributor · 1 comment

### CLI global options (--db-path, --model-name) ignored when starting MCP server

## Bug

When starting the MCP server via `mcp-local-rag` (without a subcommand), any global options passed on the command line are silently ignored.

```bash
# --db-path is parsed but never applied
mcp-local-rag --db-path /custom/path
```

The server always falls back to the env var or default, regardless of what was passed.

## Root Cause

`startServer()` accepted no arguments. `parseGlobalOptions()` runs in `index.ts` and the parsed options are available, but `startServer()` was called without

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/124) · 2026-05-14 · closed · outside contributor · 0 comments

### pnpm run check:all fails on Windows

`pnpm run check:all` fails on Windows with 24+ test failures. Root causes:
1. **Hardcoded Unix path separators** — production code (`list.ts`, `ingest.ts`, `server/index.ts`) used `/` instead of `path.sep`; tests used literal `/path/to/...` assertions
2. **Symlink EPERM on Windows** — symlink tests crash unless Developer Mode is enabled; need early-return guards
3. **Mocked `node:fs/promises` leaking via `isolate: false`** — 3 CLI test files mocked `node:fs/promises` without `realpath`, breaking

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/119) · 2026-05-12 · closed · outside contributor · 0 comments

### Feature: Add get-context command to retrieve adjacent chunks

Problem: 
When a query returns a relevant chunk, there's no easy way to retrieve the surrounding context (neighboring chunks before/after it).

Possible Solution: 
Add a new CLI command (and MCP tool) that retrieves a chunk and its neighbors:
npx mcp-local-rag get-context --file <path> --chunk-index 305 --range 3
Would return chunks 302–308 (3 before + chunk 305 + 3 after)
Flags
--file <path>
--chunk-index <n>
--range <n>
--direction before|after|both(default)

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/104) · 2026-04-15 · closed · external user · 1 comment

### CHUNK_MIN_LENGTH parameter should be added

I have found this tool properly working so far by implementing the local RAG using LanceDB and All-MiniLM-L6-v2 embedder.
Issue faced by me in my pre-production stage application:
The default settings of the application leads to very small chunks in documents related to philosophy. Like chunks of 4 words, etc. Also, the average character count for the chunks built over my documents is 50 characters. While I read in README that the chunking performs 500-1000 characters chunks, I have not been abl

[Read the thread](https://github.com/shinpr/mcp-local-rag/issues/90) · 2026-03-24 · closed · external user · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/shinpr/mcp-local-rag/issues).