Overview

Local RAG MCP Server is a lightweight, privacy-first tool for searching local documents using semantic retrieval augmented with keyword boosts. It runs entirely on your machine (no Docker or cloud required), ingests common document formats, creates local embeddings, and serves a small MCP-compatible API so AI assistants and developer tools can query your files securely and offline.

The server is designed for developers who want accurate, context-aware search across manuals, specs, notes, and code-like text where exact terms matter. Rather than relying solely on generic semantic similarity, it combines vector search with keyword boosting and smart chunking so exact identifiers (for example, useEffect or error codes) surface reliably.

Features

Semantic vector search with keyword boost for exact tokens and technical terms
Local-only processing: embeddings and index stored on your machine; no external APIs needed after initial model download
Smart semantic chunking that splits text by topical boundaries instead of fixed character counts
Quality-first result filtering that groups by relevance gaps instead of arbitrary top-K
Supports PDF, DOCX, TXT, and Markdown; also accepts cleaned HTML via ingest_data
MCP-compatible server for tool integrations plus a standalone CLI
Zero-friction setup via npx (no Docker, no Python)

Installation / Configuration

Quick start — index a folder and query it from the CLI:

# Ingest a directory
npx mcp-local-rag ingest ./docs/

# Query the index
npx mcp-local-rag query "authentication API"

Set the base directory (folder that contains documents) via the BASE_DIR environment variable when running as an MCP server:

Cursor (add to ~/.cursor/mcp.json):

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/path/to/your/documents"
      }
    }
  }
}

Codex (add to ~/.codex/config.toml):

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"

Claude Code (CLI):

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y mcp-local-rag

Notes:

Documents must live under BASE_DIR to be managed by the server.
Re-ingesting the same file replaces the previous indexed version automatically.
The server itself does not fetch web pages — use ingest_data to pass pre-fetched HTML.

Available Tools

The MCP server exposes these tools (usable by AI assistants or via the CLI):

Tool name	Description
ingest_file	Index a local file (PDF, DOCX, TXT, Markdown) into the vector DB
ingest_data	Index cleaned HTML/Markdown content provided as a string (useful for fetched pages)
query_documents	Run a semantic+keyword query; returns ranked chunks with source and score
list_files	List files in BASE_DIR and their ingestion status
delete_file	Remove a file and its chunks from the index
status	Server and index status, model and storage details

Use Cases

Codebase/Docs search: Index API specs, README, and design docs. Query “Where is OAuth implemented?” or “useEffect examples” and receive chunks that contain both semantic matches and exact token hits. Example CLI:
```
npx mcp-local-rag ingest ./api-specs
npx mcp-local-rag query "authentication flow OAuth 2.0"
```
Ad-hoc web content indexing: Your assistant fetches a documentation page, cleans it, and sends the HTML to ingest_data. The server extracts main content, converts to Markdown, and indexes it without ever calling an external service. Example (assistant action):
1. Fetch https://example.com/docs -> send HTML to MCP ingest_data
2. MCP indexes the article content only (boilerplate removed)
Offline/private research: Index PDFs, whitepapers and notes on a laptop. Search locally for architecture decisions or error codes without sending files to cloud APIs.
Integrations with coding assistants: Add as an MCP server in tools like Cursor, Codex or Claude so assistants can call ingest and query tools as part of their workflows (e.g., “Ingest latest spec”, “Search for rate limiting”).

Practical notes

Supported formats: PDF, DOCX, TXT, Markdown; ingest_data accepts cleaned HTML/Markdown strings.
Storage: embeddings and metadata are kept locally in a small vector database; initial model download occurs once.
Privacy and compliance: Because everything (after setup) runs locally, your data does not leave your machine; respect copyright and site terms when ingesting third-party content.

Repository and source: https://github.com/shinpr/mcp-local-rag

Local RAG MCP Server: Lightweight Offline Document Search