MCP Local Rag

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.