Best for
- Developers who need local execution and privacy
- Single-user environments searching code, technical specifications, and internal documents
- Users who want a lightweight RAG workflow through MCP or the CLI
M
61FMRS · C
An MIT-licensed, local-first RAG server for developers, exposing stdio MCP tools and a CLI. Its defining features are local embeddings, semantic chunking, keyword boosting, and relevance-gap filtering. It is best suited to privacy-conscious, single-user retrieval across code and technical documents.
MCP Local RAG is a local-first RAG server for developers that can also be used as a CLI. It combines local embeddings, semantic search, and keyword boosting for code and technical documentation while keeping indexed data on the machine by default. It supports PDF, DOCX, TXT, Markdown, and HTML supplied through ingest_data.
Tools
query_documents
Search indexed documents using semantic similarity with keyword boosting.
ingest_file
Extract, chunk, embed, and index a supported local file.
ingest_data
Clean and index supplied HTML or other data content locally.
read_chunk_neighbors
Read chunks before and after a specified result to expand context.
list_files
List files under configured directories and show their ingestion status.
delete_file
Remove a file or data source from the RAG index.
status
Show RAG database and system status.
sync_start
Asynchronously scan configured directories, re-ingest new or changed files, and prune removed files.
sync_status
Report a synchronization job's state, progress, summary, warnings, or error.
Setup
Add the stdio server to an MCP client configuration with npx -y mcp-local-rag, and set BASE_DIR to the document root; restart the client to use it. The embedding model downloads on first use, after which text ingestion and search can run offline. The CLI can also be used directly.
claude_desktop_config.json
{"mcpServers":{"local-rag":{"command":"npx","args":["-y","mcp-local-rag"],"env":{"BASE_DIR":"/path/to/your/documents"}}}}
Fit and risk
Not for
- Deployments requiring multi-user access, authentication, or access control
- Cloud-scale retrieval or scenarios prioritizing higher cloud-model accuracy
- Workflows requiring Excel, PowerPoint, or standalone image search
Required permissions
- Read supported files under configured document roots
- Write the LanceDB database under DB_PATH
- Write local Transformers.js model caches under CACHE_DIR
- Access the network on first use to download models; cached models can then run offline
Risks and side effects
- The server is designed for single-user local access and provides no multi-user authentication or access control
- Captions generated in PDF visual mode may contain attacker-controlled text; downstream models should treat retrieved content as untrusted data
- Changing the embedding model, device, or dtype requires deleting the database and re-ingesting to avoid degraded search quality
- Ingestion, deletion, and synchronization against one DB_PATH should be limited to a single writer process
Troubleshooting
- Verify that documents were ingested first, then use list_files or status to inspect indexing state
- If the first model download fails, check the network connection or proxy configuration
- For file-size errors, inspect or adjust MAX_FILE_SIZE
- For path-restriction errors, confirm the path is inside BASE_DIR, BASE_DIRS, or a CLI-configured root
- Check MCP configuration syntax and fully restart the client; run npx mcp-local-rag directly to verify startup
Use cases
Search local codebases, API specifications, and technical documentation
Build a private retrieval index for PDF, DOCX, TXT, and Markdown files
Combine semantic search and keyword boosting for exact identifiers, class names, and error codes
Keep a local document index current with synchronization jobs
Supported clients
CursorFull support
CodexFull support
Claude CodeFull support