MCP Local RAG
Local RAG for developers using MCP. Hybrid search (BM25 + semantic) for exact technical terms — fully private, zero setup.
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
npx -y @yikizi/[email protected]O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
claude mcp add yikizi-mcp-local-rag -- npx -y @yikizi/mcp-local-rag@1.5.1Execute em um terminal.
{ "mcpServers": { "yikizi-mcp-local-rag": { "command": "npx", "args": [ "-y", "@yikizi/[email protected]" ] } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirCode-aware hybrid search
Keyword (BM25) + semantic search combined. Exact terms like useEffect, error codes, and class names are matched reliably—not just semantically guessed.
Quality-first result filtering Groups results by relevance gaps instead of arbitrary top-K cutoffs. Get fewer but more trustworthy chunks.
Runs entirely locally No API keys, no cloud, no data leaving your machine. Works fully offline after the first model download.
Zero-friction setup
One npx command. No Docker, no Python, no servers to manage. Designed for Cursor, Codex, and Claude Code via MCP.
Set BASE_DIR to the folder you want to search. Documents must live under it.
Add the MCP server to your AI coding tool:
For Cursor — Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": ["-y", "mcp-local-rag"],
"env": {
"BASE_DIR": "/path/to/your/documents"
}
}
}
}
For 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"
For Claude Code — Run this command:
claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y mcp-local-rag
Restart your tool, then start using it:
You: "Ingest api-spec.pdf"
Assistant: Successfully ingested api-spec.pdf (47 chunks created)
You: "What does the API documentation say about authentication?"
Assistant: Based on the documentation, authentication uses OAuth 2.0 with JWT tokens.
The flow is described in section 3.2...
That's it. No installation, no Docker, no complex setup.
You want AI to search your documents—technical specs, research papers, internal docs. But most solutions send your files to external APIs.
Privacy. Your documents might contain sensitive data. This runs entirely locally.
Cost. External embedding APIs charge per use. This is free after the initial model download.
Offline. Works without internet after setup.
Code search. Pure semantic search misses exact terms like useEffect or ERR_CONNECTION_REFUSED. Hybrid search catches both meaning and exact matches.
The server provides 5 MCP tools: ingest, search, list, delete, status
(ingest_file, query_documents, list_files, delete_file, status).
The server provides six tools through MCP:
Document ingestion handles PDF, DOCX, TXT, Markdown, and code files (TypeScript, JavaScript, Python, Java, Go, Rust, C/C++, Ruby, PHP, C#, Shell, SQL). Point it at a file, and it extracts the text, splits it into searchable chunks, generates embeddings using a local model, and stores everything in a local vector database. If you ingest the same file again, it replaces the old version—no duplicate data.
Text snippet memorization lets you store code snippets, notes, or any text directly without file I/O using the memorize_text tool. Perfect for quick note-taking or caching frequently referenced code. Snippets are stored with synthetic paths like memory://label and can be deleted like regular files.
Semantic search uses hybrid search combining BM25 keyword matching with vector similarity. Ask "how does authentication work" and it finds relevant sections using both exact keyword matches and semantic understanding.
File management shows what you've ingested and when. You can see how many chunks each file produced and verify everything is indexed correctly.
File deletion removes ingested documents from the vector database. When you delete a file, all its chunks and embeddings are permanently removed. This is useful for removing outdated documents or sensitive data you no longer want indexed.
System status reports on your database—document count, total chunks, memory usage, and search mode (hybrid or vector-only). Helpful for monitoring performance or debugging issues.
All of this uses:
The result: query responses typically under 3 seconds on a standard laptop, even with thousands of document chunks indexed.
The server starts instantly, but the embedding model downloads on first use (when you ingest or search for the first time):
You'll see a message like "Initializing model (downloading ~90MB, may take 1-2 minutes)..." in the console. The model caches in CACHE_DIR (default: ./models/) for offline use.
Why lazy initialization? This approach allows the server to start immediately without upfront model loading. You only download when actually needed, making the server more responsive for quick status checks or file management operations.
Offline Mode: After first download, works completely offline—no internet required.
Path Restriction: This server only accesses files within your BASE_DIR. Any attempt to access files outside this directory (e.g., via ../ path traversal) will be rejected.
Local Only: All processing happens on your machine. No network requests are made after the initial model download.
Model Verification: The embedding model downloads from HuggingFace's official repository (Xenova/all-MiniLM-L6-v2). Verify integrity by checking the official model card.
The server works out of the box with sensible defaults, but you can customize it through environment variables.
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"
DB_PATH = "./lancedb"
CACHE_DIR = "./models"
Supports PDF, DOCX, TXT, and Markdown. The server extracts text, splits it into chunks, generates embeddings locally, and stores everything in a local vector database.
Re-ingesting the same file replaces the old version automatically.
"What does the API documentation say about authentication?"
"Find information about rate limiting"
"Search for error handling best practices"
The hybrid search combines keyword matching (BM25) with semantic search. This means useEffect finds documents containing that exact term, not just semantically similar React concepts.
Results include text content, source file, and relevance score. Adjust result count with limit (1-20, default 10). Use offset (0-1000) for pagination through large result sets.
"List all ingested files" # See what's indexed
"Delete old-spec.pdf from RAG" # Remove a file
"Show RAG server status" # Check system health
Adjust these for your use case:
Example (stricter, code-focused):
"env": {
"RAG_HYBRID_WEIGHT": "0.7",
"RAG_GROUPING": "similar"
}
TL;DR:
When you ingest a document, the parser extracts text based on file type (PDF via pdf-parse, DOCX via mammoth, text files directly).
The chunker splits text using LangChain's RecursiveCharacterTextSplitter—breaking on natural boundaries while keeping chunks around 512 characters with 100-character overlap.
Each chunk goes through the Transformers.js embedding model (all-MiniLM-L6-v2), converting text into 384-dimensional vectors. Vectors are stored in LanceDB, a file-based vector database requiring no server process.
When you search:
The keyword-heavy default works well for developer documentation where exact terms matter.
Cursor — Global: ~/.cursor/mcp.json, Project: .cursor/mcp.json
{
"mcpServers": {
"local-rag": {
"command": "npx",
"args": ["-y", "mcp-local-rag"],
"env": {
"BASE_DIR": "/path/to/your/documents"
}
}
}
}
Codex — ~/.codex/config.toml (note: must use mcp_servers with underscore)
[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]
[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"
Claude Code:
claude mcp add local-rag --scope user \
--env BASE_DIR=/path/to/your/documents \
-- npx -y mcp-local-rag
The embedding model (~90MB) downloads on first use. Takes 1-2 minutes, then works offline.
BASE_DIR are accessibleTested on MacBook Pro M1 (16GB RAM), Node.js 22:
Query Speed: ~1.2 seconds for 10,000 chunks (p90 < 3s)
Ingestion (10MB PDF):
Memory: ~200MB idle, ~800MB peak (50MB file ingestion)
Concurrency: Handles 5 parallel queries without degradation.
Documents must be ingested first. Run "List all ingested files" to verify.
Check internet connection. If behind a proxy, configure network settings. The model can also be downloaded manually.
Default limit is 100MB. Split large files or increase MAX_FILE_SIZE.
Check chunk count with status. Consider increasing CHUNK_SIZE to reduce the number of chunks (trade-off: larger chunks may reduce retrieval precision).
Ensure file paths are within BASE_DIR. Use absolute paths.
npx mcp-local-rag should run without errorsIs this really private? Yes. After model download, nothing leaves your machine. Verify with network monitoring.
Can I use this offline? Yes, after the first model download (~90MB).
How does this compare to cloud RAG? Cloud services offer better accuracy at scale but require sending data externally. This trades some accuracy for complete privacy and zero runtime cost.
What file formats are supported? PDF, DOCX, TXT, Markdown. Not yet: Excel, PowerPoint, images, HTML.
Can I change the embedding model? Yes, but you must delete your database and re-ingest all documents. Different models produce incompatible vector dimensions.
GPU acceleration? Transformers.js runs on CPU. GPU support is experimental. CPU performance is adequate for most use cases.
Multi-user support? No. Designed for single-user, local access. Multi-user would require authentication/access control.
How to backup?
Copy DB_PATH directory (default: ./lancedb/).
git clone https://github.com/shinpr/mcp-local-rag.git
cd mcp-local-rag
npm install
npm test # Run all tests
npm run test:coverage # With coverage
npm run test:watch # Watch mode
npm run type-check # TypeScript check
npm run check:fix # Lint and format
npm run check:deps # Circular dependency check
npm run check:all # Full quality check
src/
index.ts # Entry point
server/ # MCP tool handlers
parser/ # PDF, DOCX, TXT, MD parsing
chunker/ # Text splitting
embedder/ # Transformers.js embeddings
vectordb/ # LanceDB operations
__tests__/ # Test suites
Each module has clear boundaries:
Test Environment: MacBook Pro M1 (16GB RAM), tested with v0.1.3 on Node.js 22 (January 2025)
Query Performance:
Ingestion Speed (10MB PDF):
Memory Usage:
Concurrent Queries: Handles 5 parallel queries without degradation. LanceDB's async API allows non-blocking operations.
Note: Your results will vary based on hardware, especially CPU speed (embeddings run on CPU, not GPU).
Cause: Documents must be ingested before searching.
Solution:
"Ingest /path/to/document.pdf""List all ingested files""Search for [your query]"Common mistake: Trying to search immediately after configuration without ingesting any documents.
The embedding model downloads from HuggingFace on first use (when you ingest or search for the first time). If you're behind a proxy or firewall, you might need to configure network settings.
When it happens: Your first ingest or search operation will trigger the download. If it fails, you'll see a detailed error message with troubleshooting guidance (network issues, disk space, cache corruption).
What to do: The error message provides specific recommendations. Common solutions:
Alternatively, download the model manually:
Default limit is 100MB. For larger files:
If queries take longer than expected:
status command)The server restricts file access to BASE_DIR for security. Make sure your file path is within that directory. Check for:
For Cursor:
For Codex CLI:
~/.codex/config.toml to verify the configuration[mcp_servers.local-rag] (with underscore)npx mcp-local-rag should run without errorsFor Claude Code:
claude mcp list to see configured servers~/.config/claude/mcp_config.json for syntax errorsnpx mcp-local-rag should run without errorsCommon issues:
npm install -g mcp-local-rag)When you ingest a document, the parser extracts text based on the file type. PDFs use pdf-parse, DOCX uses mammoth, and text files are read directly.
The chunker then splits the text using LangChain's RecursiveCharacterTextSplitter. It tries to break on natural boundaries (paragraphs, sentences) while keeping chunks around 512 characters. Adjacent chunks overlap by 100 characters to preserve context.
Each chunk goes through the Transformers.js embedding model, which converts text into a 384-dimensional vector representing its semantic meaning. This happens in batches of 8 chunks at a time for efficiency.
Vectors are stored in LanceDB, a columnar vector database that works with local files. No server process, no complex setup. It's just a directory with data files.
When you search, your query becomes a vector using the same model. LanceDB finds the chunks with vectors most similar to your query vector (using cosine similarity). The top matches return to your MCP client with their original text and metadata.
The beauty of this approach: semantically similar text has similar vectors, even if the words are different. "authentication process" and "how users log in" will match each other, unlike keyword search.
Is this really private?
Yes. After the initial model download, nothing leaves your machine. You can verify with network monitoring tools—no outbound requests during ingestion or search.
Can I use this offline?
Yes, once the model is cached. The first run needs internet to download the model (~90MB), but after that, everything works offline.
How does this compare to cloud RAG services?
Cloud services (OpenAI, Pinecone, etc.) typically offer better accuracy and scale. But they require sending your documents externally, ongoing costs, and internet connectivity. This project trades some accuracy for complete privacy and zero runtime cost.
What file formats are supported?
Currently supported:
.pdf (uses pdf-parse).docx (uses mammoth, not .doc).txt.md, .markdown.ts, .tsx.js, .jsx.py.java.go.rs.c, .cpp, .cc, .cxx, .h, .hpp.rb.php.cs.sh.sqlmemorize_text tool (no file needed)Not yet supported:
.xlsx, .csv).pptx).jpg, .png).html).doc)Want support for another format? Open an issue with your use case.
Can I customize the embedding model?
Yes, set MODEL_NAME to any Transformers.js-compatible model from HuggingFace. Keep in mind that different models have different vector dimensions, so you'll need to rebuild your database if you switch.
How much does accuracy depend on the model?
all-MiniLM-L6-v2 is optimized for English and performs well for technical documentation. For other languages, consider multilingual models like multilingual-e5-small. For higher accuracy, try larger models—but expect slower processing.
What about GPU acceleration?
Transformers.js runs on CPU by default. GPU support is experimental and varies by platform. For most use cases, CPU performance is adequate (embeddings are reasonably fast even without GPU).
Can multiple people share a database?
The current design assumes single-user, local access. For multi-user scenarios, you'd need to implement authentication and access control—both out of scope for this project's privacy-first design.
How do I back up my data?
Copy your DB_PATH directory (default: ./lancedb/). That's your entire vector database. Copy BASE_DIR for your original documents. Both are just files—no special export needed.
Contributions welcome. Before submitting a PR:
npm testnpm run check:allMIT License. Free for personal and commercial use.
Built with Model Context Protocol by Anthropic, LanceDB, Transformers.js, and LangChain.js.
Local RAG MCP Server - Enhanced with hybrid search, memory management, and code file support (fork of shinpr/mcp-local-rag)
{ "mcpServers": { "yikizi-mcp-local-rag": { "command": "npx", "args": [ "-y", "@yikizi/[email protected]" ] } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
@yikizi/mcp Local Rag roda localmente via stdio.
Última verificação: 2026-11-13. Local RAG MCP Server - Enhanced with hybrid search, memory management, and code file support (fork of shinpr/mcp-local-rag)