mcp-local-rag — Claude Code MCP server: what it does, how to install
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.
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-ragWhat mcp-local-rag 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.
What it helps with
- 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 for the agent
- "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."
How to install mcp-local-rag
Platform CLI
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-ragReplace <…> with your own values. 15 more environment variables are in the server README
Platform CLI
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-ragReplace <…> with your own values. 15 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-ragReplace <…> with your own values. 15 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-local-rag
How do I install mcp-local-rag in Claude Code?
Run `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, replacing <BASE_DIR>` with the absolute path to your documents directory.
What does mcp-local-rag do?
It indexes local PDF, DOCX, TXT, and Markdown files so your coding assistant can search them using vector similarity and keyword filtering. It returns relevant text excerpts with line or page numbers without sending your files to cloud services.
What prerequisites are needed to run this server?
It requires Node.js version 22.20 or newer. You only need network access on the initial run to download the roughly 90 MB embedding model; after that, everything runs offline.
