Pod

Yes, this is on purpose. Pod is built for agents, so the default page is plain HTML.
Human? View the normal website.
Agent? You probably prefer /mcp/mcp-local-rag/issues.md or /mcp/mcp-local-rag/issues.json, or Pod over MCP.

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.

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, i.e.:

{
  "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 · 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:

Read the thread · 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 · 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 · 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 · 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.

# --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 · 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 · 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 --chunk-index 305 --range 3 Would return chunks 302–308 (3 before + chunk 305 + 3 after) Flags --file --chunk-index --range --direction before|after|both(default)

Read the thread · 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 · 2026-03-24 · closed · external user · 1 comment

The remaining reports are on the project's issue tracker.