rag-vault
One command. Zero cloud. Your docs stay private.
Install / Use
claude mcp add RobThePCGuy -- npx -y github:RobThePCGuy/rag-vaultIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of rag-vault
rag-vault scores 76/100 on our quality scale, 809th of 947 AI & Machine Learning skills we index.
Its MCP Server is 23 KB long, well organised into 68 sections with 24 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so rag-vault is actively maintained.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 75/100, with 3 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-15. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
rag-vault compared with similar skills
All 4 of these similar skills score higher than rag-vault; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| rag-vault (this skill)by RobThePCGuy | 76 | 3 | today | MCP Server |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install rag-vault?
- Run
claude mcp add RobThePCGuy -- npx -y github:RobThePCGuy/rag-vault. The install tabs above show the steps for each supported agent. - Which AI agents does rag-vault work with?
- It is written for Claude Code, Claude Desktop, Cursor and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is rag-vault safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 75/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is rag-vault still maintained?
- The repository was last updated today, so rag-vault is actively maintained.
Skill content
View source on GitHubRAG Vault
Your documents. Your machine. Your control.
RAG Vault lets your AI coding assistant search your private documents, things like API specs, research papers, and internal docs. Everything runs locally and your data stays on your machine unless you choose to pull in content from a remote URL.
One command to run, minimal setup, privacy by default.
Why RAG Vault?
| Pain Point | RAG Vault Solution |
|------------|-------------------|
| "I don't want my docs on someone else's server" | Everything stays local by default. No background cloud calls for indexing or search. |
| "Semantic search misses exact code terms" | Hybrid search with RRF fusion, optional cross-encoder reranking |
| "Setup requires Docker, Python, databases..." | One npx command plus a small MCP config block. |
| "Cloud APIs charge per query" | Free forever. No subscriptions. |
Security
RAG Vault comes with security built in:
- API Authentication: Optional API key via
RAG_API_KEY - Rate Limiting: You can throttle requests
- CORS Control: Restrict allowed origins
- Security Headers: Helmet.js protection
See SECURITY.md for complete documentation.
First-Time Setup Checklist
Before adding MCP config:
- Install Node.js 20 or newer.
- Pick a documents directory and set
BASE_DIRto that path. - Make sure your AI tool process can read
BASE_DIR. - Restart your AI tool after editing config.
Get Started Quickly
For Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"local-rag": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:RobThePCGuy/rag-vault"],
"env": {
"BASE_DIR": "/path/to/your/documents"
}
}
}
}
Replace /path/to/your/documents with your real absolute path.
For Claude Code
Add to .mcp.json in your project directory:
{
"mcpServers": {
"local-rag": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:RobThePCGuy/rag-vault"],
"env": {
"BASE_DIR": "./documents",
"DB_PATH": "./documents/.rag-db",
"CACHE_DIR": "./.cache",
"RAG_EMBEDDING_DEVICE": "cpu",
"RAG_HYBRID_WEIGHT": "0.6",
"RAG_GROUPING": "related"
}
}
}
}
Or add inline via CLI:
claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y github:RobThePCGuy/rag-vault
For Codex
Add to ~/.codex/config.toml:
[mcp_servers.local-rag]
command = "npx"
args = ["-y", "github:RobThePCGuy/rag-vault"]
[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"
Install Skills (Optional)
If you want your AI to write better queries and make more sense of results, install the RAG Vault skills:
# Claude Code (project-level - recommended for team projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code
# Claude Code (user-level - available in all projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code --global
# Codex (user-level)
npx github:RobThePCGuy/rag-vault skills install --codex
# Custom location
npx github:RobThePCGuy/rag-vault skills install --path /your/custom/path
Skills teach Claude best practices for:
- Query formulation and expansion strategies
- Score interpretation. In boost mode, under 0.3 is a good match and over 0.5 is worth skipping. RRF mode scores by rank instead.
- When to use
ingest_filevsingest_data - HTML ingestion and URL handling
Restart your AI tool, and start talking:
You: "Ingest api-spec.pdf"
AI: Successfully ingested api-spec.pdf (47 chunks)
You: "How does authentication work?"
AI: Based on section 3.2, authentication uses OAuth 2.0 with JWT tokens...
That's it. No Docker. No Python. No server infrastructure to manage.
Web Interface
RAG Vault has a web UI so you can manage your documents without touching the command line.
Launch the Web UI
npx github:RobThePCGuy/rag-vault web
Open http://localhost:3000 in your browser.
By default the web server binds to
127.0.0.1(loopback), so it is reachable only from this machine. To use it from another device on your network, setRAG_BIND_HOST=0.0.0.0— and setRAG_API_KEYas well, since the API is otherwise unauthenticated.
What You Can Do
- Upload documents: Drag and drop PDF, DOCX, Markdown, TXT, JSON, JSONL, and NDJSON files
- Search instantly: Type queries and see results with relevance scores
- Preview content: Click any result to see the full chunk in context
- Manage files: View all indexed documents and delete what you don't need
- Switch databases: Create and switch between multiple knowledge bases
- Monitor status: See document counts, memory usage, and search mode
- Export/Import settings: Back up and restore your vault configuration
- Theme preferences: Switch between light, dark, or system theme
- Folder browser: Navigate directories to select documents
REST API
The web server has a REST API you can hit directly. Set RAG_API_KEY to require authentication:
# With authentication (when RAG_API_KEY is set)
curl -X POST "http://localhost:3000/api/v1/search" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"query": "authentication", "limit": 5}'
# Search documents (no auth needed if RAG_API_KEY isn't set)
curl -X POST "http://localhost:3000/api/v1/search" \
-H "Content-Type: application/json" \
-d '{"query": "authentication", "limit": 5}'
# List all files
curl "http://localhost:3000/api/v1/files"
# Upload a document
curl -X POST "http://localhost:3000/api/v1/files/upload" \
-F "file=@spec.pdf"
# Delete a file
curl -X DELETE "http://localhost:3000/api/v1/files" \
-H "Content-Type: application/json" \
-d '{"filePath": "/path/to/spec.pdf"}'
# Get system status
curl "http://localhost:3000/api/v1/status"
# Health check (for load balancers)
curl "http://localhost:3000/api/v1/health"
Reader API Endpoints
These endpoints let you read documents and find connections across them:
# Get all chunks for a document (ordered by index)
curl "http://localhost:3000/api/v1/documents/chunks?filePath=/path/to/doc.pdf"
# Find related chunks for cross-document discovery
curl "http://localhost:3000/api/v1/chunks/related?filePath=/path/to/doc.pdf&chunkIndex=0&limit=5"
# Batch request for multiple chunks (efficient for UIs)
curl -X POST "http://localhost:3000/api/v1/chunks/batch-related" \
-H "Content-Type: application/json" \
-d '{"chunks": [{"filePath": "/path/to/doc.pdf", "chunkIndex": 0}], "limit": 3}'
Remote Mode
RAG Vault can also run as an HTTP server so remote MCP clients like Claude.ai, Claude Desktop, or anything that supports Streamable HTTP or SSE can connect to it.
# Start remote server (default port 3001)
npx github:RobThePCGuy/rag-vault --remote
# Custom port
npx github:RobThePCGuy/rag-vault --remote --port 8080
Stdio mode is unchanged. Just leave off --remote and everything works as before with Cursor, Claude Code, and Codex.
Connecting from Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"rag-vault-remote": {
"type": "url",
"url": "http://localhost:3001/mcp"
}
}
}
Or via Claude Code CLI:
claude mcp add --transport http rag-vault http://localhost:3001/mcp
Connecting from Claude.ai
For Claude.ai (Pro/Max/Team/Enterprise), add as a custom connector with URL https://your-host:3001/mcp. For local development, expose your server with a tunnel:
cloudflared tunnel --url http://localhost:3001
The remote server also binds to 127.0.0.1 (loopback) by default. To accept connections from other machines directly, set RAG_BIND_HOST=0.0.0.0. Set RAG_API_KEY for authentication whenever you expose the server beyond loopback (including via a tunnel). The server supports both Streamable HTTP (/mcp) and legacy SSE (/sse) transports, plus a health check at /health.
Real-World Examples
Search Your Codebase Documentation
You: "Ingest all the markdown files in /docs"
AI: Ingested 23 files (847 chunks total)
You: "What's the retry policy for failed API calls?"
AI: According to error-handling.md, failed requests retry 3 times
with exponential backoff: 1s, 2s, 4s...
Index Web Documentation
You: "Fetch https://docs.example.com/api and ingest the HTML"
AI: Ingested "docs.example.com/api" (156 chunks)
You: "What rate limits apply to the /users endpoint?"
AI: The API limits /users to 100 requests per minute per API key...
Build a Personal Knowledge Base
You: "Ingest my research papers folder"
AI: Ingested 12 PDFs (2,341 chunks)
You: "What do recent studies say about transformer attention mechanisms?"
AI: Based on attention-mechanisms-2024.pdf, the key finding is...
Search Exact Technical Terms
RAG Vault's hybrid search catches both meaning and exact matches:
You: "Search for ERR_CONNECTION_REFUSED"
AI: Found 3 results mentioning ERR_CONNECTION_REFUSED:
1. troubleshooting.md - "When you see ERR_CONNECTION_REFUSED..."
2. network-errors.pdf - "Common causes include..."
Pure semantic search would miss this. RAG Vault finds it.
How It Works
Document → Parse → Chunk by meaning → Embed locally → Store in LanceDB
↓
Query → Embed → Vector search + BM25 → Fusion → Optional reranking → Results
Smart chunking: Splits by meaning, not character count. Keeps code blocks intact.
Hybrid search: Two fusion modes that combine vector similarity with BM25 keyword matching:
- Boost mode (default): BM25 boosts vector search distances multiplicatively. Simple and predictable.
- RRF mode (opt-in via
RAG_SEARCH_MODE=rrf): Reciprocal Rank Fusion treats vector and BM25 as independent voters. This can surface documents that vector search alone would miss.
Cross-encoder reranking (opt-in): After the first pass, a cross-encoder model (Xenova/ms-marco-MiniLM-L-6-v2, ~23MB) scores each (query, passage) pair together for tighter relevance ranking. Turn it on with RAG_RERANKER_ENABLED=true.
Query expansion (opt-in): Generates reformulated queries to improve recall when searches are paraphrased or conceptual. Two backends: local template-based expansion (default, fully offline) or LLM-based HyDE through an external API. Turn it on with RAG_HYDE_ENABLED=true.
Quality filtering: Groups results by relevance gaps instead of arbitrary top-K cutoffs.
Local by default: Embeddings via Transformers.js. Storage via LanceDB. Network is only needed for initial model download or if you explicitly ingest remote URLs.
MCP tools included: query_documents, ingest_file, ingest_data, delete_file, list_files, status, feedback_pin, feedback_dismiss, and feedback_stats.
Supported Formats
| Format | Extension | Notes |
|--------|-----------|-------|
| PDF | .pdf | Full text extraction, header/footer filtering |
| Word | .docx | Tables, lists, formatting preserved |
| Markdown | .md | Code blocks kept intact |
| Text | .txt | Plain text |
| JSON | .json | Converted to searchable key-value text |
| JSONL / NDJSON | .jsonl, .ndjson | Parsed line-by-line for logs and structured records |
| HTML | via ingest_data | Auto-cleaned with Readability |
Configura
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
