# mcp-local-rag

Local semantic and keyword search for PDF, DOCX, and Markdown files without sending data to external APIs. Useful for querying internal technical docs directly from an agent.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 421
- Author: shinpr
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/shinpr/mcp-local-rag
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-local-rag

## What it does

The server indexes PDF, DOCX, TXT, and Markdown files on the local machine. It combines semantic vector search with keyword matching. Because of this hybrid approach, the agent catches conceptual meaning alongside exact error codes or API signatures. Responses return relevant passages with page numbers, line numbers, or headings.

No Docker, Python, or external database is needed. You only need Node.js 22.20 or later. An internet connection is required solely on the first run to fetch the roughly 90 MB embedding model. After that download, all parsing and search operations run completely offline.

The directory specified in `BASE_DIR` acts as the security boundary. The server refuses to read files outside of it. Source code extensions, Excel sheets, and PowerPoint presentations are unsupported for direct file indexing.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `BASE_DIR`, `BASE_DIRS`, `IGNORE_PATHS`, `DB_PATH`, `CACHE_DIR`, `HF_ENDPOINT`, `MODEL_NAME`, `MAX_FILE_SIZE`, `RAG_MAX_DISTANCE`, `RAG_GROUPING` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env BASE_DIR=<BASE_DIR> --env BASE_DIRS=<BASE_DIRS> --env IGNORE_PATHS=<IGNORE_PATHS> --env DB_PATH=<DB_PATH> --env CACHE_DIR=<CACHE_DIR> --transport stdio mcp-local-rag -- npx -y mcp-local-rag
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add mcp-local-rag --env BASE_DIR=<BASE_DIR> --env BASE_DIRS=<BASE_DIRS> --env IGNORE_PATHS=<IGNORE_PATHS> --env DB_PATH=<DB_PATH> --env CACHE_DIR=<CACHE_DIR> -- npx -y mcp-local-rag
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-local-rag": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-local-rag"
            ],
            "env": {
                "BASE_DIR": "<BASE_DIR>",
                "BASE_DIRS": "<BASE_DIRS>",
                "IGNORE_PATHS": "<IGNORE_PATHS>",
                "DB_PATH": "<DB_PATH>",
                "CACHE_DIR": "<CACHE_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. 15 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-local-rag": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "mcp-local-rag"
            ],
            "env": {
                "BASE_DIR": "<BASE_DIR>",
                "BASE_DIRS": "<BASE_DIRS>",
                "IGNORE_PATHS": "<IGNORE_PATHS>",
                "DB_PATH": "<DB_PATH>",
                "CACHE_DIR": "<CACHE_DIR>"
            }
        }
    }
}
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e BASE_DIR=<BASE_DIR> -e BASE_DIRS=<BASE_DIRS> -e IGNORE_PATHS=<IGNORE_PATHS> -e DB_PATH=<DB_PATH> -e CACHE_DIR=<CACHE_DIR> mcp-local-rag npx -y mcp-local-rag
```
Replace <…> with your own values. 15 more environment variables are in the server README

## When to use it
- search private PDF, DOCX, and Markdown documents without sending text to external APIs
- look up exact function names and error codes through hybrid retrieval
- retrieve source passages with page numbers and line references
- re-index local document directories without maintaining external databases

## Example prompts
- "Update the index for the document directory and report when finished."
- "Search our local docs for details on ERR_CONNECTION_REFUSED."
- "Fetch adjacent chunks around the selected documentation passage."

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md