Log inSubmit server
MCP Local Rag logo

MCP Local Rag

by shinpr

Indexes local PDFs, DOCX, text, and Markdown files for private semantic and keyword-boosted search.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Local Rag

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "shinpr-mcp-local-rag": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-local-rag"
      ],
      "env": {
        "BASE_DIR": "YOUR_VALUE_HERE",
        "BASE_DIRS": "YOUR_VALUE_HERE",
        "IGNORE_PATHS": "YOUR_VALUE_HERE",
        "DB_PATH": "YOUR_VALUE_HERE",
        "CACHE_DIR": "YOUR_VALUE_HERE",
        "HF_ENDPOINT": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

shinpr/mcp-local-rag indexes local PDFs, DOCX, Markdown, and text files with local embeddings stored in LanceDB. Its MCP tools support directory synchronization, individual ingestion, semantic search with keyword matching, neighboring-chunk reading, and index management. Use it when an MCP client needs to search private documents without sending content to an embedding API or cloud service. HTML and in-memory text can also be added when the client has already fetched or holds the content.

Use cases

  • Search private API documentation locally
  • Index project manuals and guides
  • Find exact error codes in technical files
  • Inspect context around matching passages
  • Ingest HTML fetched by an MCP client

Key features

  • Local embeddings with LanceDB storage
  • Semantic search with keyword boosting
  • PDF, DOCX, TXT, and Markdown ingestion
  • Incremental synchronization and deletion tracking
  • Neighboring-chunk context retrieval

Tools9

What MCP Local Rag lets your agent do. Expand a tool for its parameters.

Self-reported~120 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

19/20 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · mcp-local-rag (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars425Stargazers on the source repository.
npm downloads10kPackage downloads in the last 30 days.
Last commit5d agoMost recent push to the default branch.
Tools exposed9Callable tools this server registers over MCP.
Directory activity14 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Local Rag works

What shinpr/mcp-local-rag does

It combines semantic similarity with keyword matching, which helps queries find both conceptually related passages and exact terms such as API names, class names, or error codes. Search results include source passages and may include headings, line numbers, or page numbers for checking the original material.

The index uses LanceDB for vector storage and a locally cached embedding model. After the initial model download, ingestion and searching can run offline. No API key, Docker installation, Python runtime, or external database is needed.

How it works

Configure one document root with BASE_DIR, or multiple roots with BASE_DIRS. A synchronization operation compares the configured files with the index, skips unchanged files, and removes entries for files that have been deleted. You can also ingest or replace one file directly, or pass text, Markdown, or already-fetched HTML through ingest_data with a stable source identifier.

MCP paths must be absolute and remain inside a configured document root. When a document changes, run synchronization or ingest that file again. Search can be followed by a neighboring-chunk request to inspect more context around a returned result. The command-line interface provides equivalent operations for ingestion, synchronization, querying, listing, status checks, and deletion.

The first use downloads the default embedding model, which is about 90 MB and requires internet access. Subsequent runs use the local model cache. The server can be started through an MCP client's standard command configuration with npx -y mcp-local-rag, or used directly from the terminal with the package's CLI.

Setup and configuration

Node.js 22.20 or newer is required. Set BASE_DIR to an absolute directory containing the documents to index. BASE_DIRS accepts a JSON array of roots and takes precedence over BASE_DIR; IGNORE_PATHS accepts JSON glob patterns for excluding files. Set DB_PATH to choose the LanceDB location and CACHE_DIR to choose the embedding-model cache. Absolute paths are recommended for both so separate working directories do not create different indexes unintentionally.

Register the package with an MCP client, restart that client, and request a full synchronization. Claude Code, Codex, and Cursor configurations are shown using the npx command. The CLI defaults to the current directory as its document root, so ingestion and querying should use the same working directory unless paths are configured explicitly.

Tools and capabilities

  • sync_start reconciles all configured roots or a selected path.
  • sync_status reports progress for an active synchronization job.
  • ingest_file adds or replaces one supported file.
  • ingest_data indexes client-held text, Markdown, or HTML.
  • query_documents performs semantic search with keyword boosting.
  • read_chunk_neighbors returns surrounding chunks for a search result.
  • list_files shows supported files and their ingestion state.
  • delete_file removes an indexed file or an item created with ingest_data.
  • status reports index and search state.

Limitations and notes

File ingestion does not support Excel, PowerPoint, standalone images, or source-code extensions. HTML retrieval is outside the server: an MCP client must fetch the page and submit its HTML. PDF figures can optionally be described with a local vision model, but this feature is not OCR or image search. PDF section headings may be inaccurate, so consult the original page when exact headings matter.

Keep the database and model cache paths consistent between MCP and CLI usage. When moving a project, stop other database writers, move the files and database without changing their relative layout, relocate the index, update the configured paths, and restart the client.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Local Rag

shinpr/mcp-local-rag is an MCP server that connects AI clients to local PDF, DOCX, TXT, Markdown, and client-supplied HTML or text content. Its main tools synchronize and ingest files, run semantic and keyword-boosted searches, read neighboring chunks, list indexed files, delete entries, and report index status.

Install it through an MCP client by running `npx -y mcp-local-rag` and setting `BASE_DIR` to an absolute document directory. Node.js 22.20 or newer is required, and the first run downloads the package and embedding model.

Yes, shinpr/mcp-local-rag works with Cursor through its MCP configuration. Add an entry that runs `npx` with `-y mcp-local-rag`, set `BASE_DIR` in the entry's environment, restart Cursor, and synchronize the document root.

It supports PDF, DOCX, TXT, and Markdown files through file ingestion or directory synchronization. Client-held plain text, Markdown, and already-fetched HTML can be submitted with `ingest_data`; Excel, PowerPoint, standalone images, and source-code extensions are not supported by file ingestion.

Related MCP servers

All in Knowledge & Memory All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Local Rag AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/shinpr-mcp-local-rag?style=directory)](https://allmcps.com/mcp/shinpr-mcp-local-rag)
HTML Embed
<a href="https://allmcps.com/mcp/shinpr-mcp-local-rag"><img src="https://allmcps.com/api/badge/shinpr-mcp-local-rag?style=directory" alt="MCP Local Rag on AllMCPs" /></a>