# rag-vault MCP server

> Enables AI clients to perform local hybrid semantic search and document ingestion for private files like PDFs, DOCX, and Markdown.

- Repository: https://github.com/RobThePCGuy/rag-vault
- Page: https://hostedmcp.org/servers/robthepcguy/rag-vault
- Transport: stdio
- Stars: 3
- Latest version: 1.5.3

## Install

### Claude Code

```sh
claude mcp add rag-vault -- npx -y @robthepcguy/rag-vault
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "rag-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@robthepcguy/rag-vault"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "rag-vault": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@robthepcguy/rag-vault"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"rag-vault","type":"stdio","command":"npx","args":["-y","@robthepcguy/rag-vault"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "rag-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@robthepcguy/rag-vault"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add rag-vault -- npx -y @robthepcguy/rag-vault
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.rag-vault]
command = "npx"
args = ["-y", "@robthepcguy/rag-vault"]
```

### Gemini CLI

```sh
gemini mcp add -s user rag-vault npx -- -y @robthepcguy/rag-vault
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "rag-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@robthepcguy/rag-vault"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BASE_DIR` | no | no | Base directory for document storage (defaults to current working directory) |
| `CACHE_DIR` | no | no | Directory where Transformers.js models are cached (defaults to ./models/) |
| `DB_PATH` | no | no | Path to LanceDB database directory (defaults to ./lancedb/) |
| `MODEL_NAME` | no | no | Embedding model name (defaults to Xenova/all-MiniLM-L6-v2) |
| `RAG_EMBEDDING_DEVICE` | no | no |  |
| `RAG_GROUPING` | no | no | Grouping mode: 'similar' (top group only) or 'related' (top 2 groups) |
| `RAG_HYBRID_WEIGHT` | no | no | Keyword boost strength for hybrid search. 0.0 = semantic only, 1.0 = keyword only. Default 0.6 |

## Tools (9)

- `query_documents`: Search ingested documents using hybrid semantic + keyword search. Advanced syntax supported: - "exact phrase" → Match phrase exactly - field:value → Filter by custom metadata (e.g., domain:legal, author:john) - term1 AND term2 → Both terms required (default) - term1 OR term2 → Either term matches - -term → Exclude results containing term Results include score (0 = most relevant, higher = less relevant). Set explain=true to see why each result matched.
- `ingest_file`: Ingest a document file (PDF, DOCX, TXT, MD, JSON, JSONL) into the vector database for semantic search. File path must be an absolute path. Supports re-ingestion to update existing documents. Optional metadata can include author, domain, tags, etc.
- `ingest_data`: Ingest content as a string, not from a file. Use for: fetched web pages (format: html), copied text (format: text), or markdown strings (format: markdown). The source identifier enables re-ingestion to update existing content. Optional custom metadata can include author, domain, tags, etc. For files on disk, use ingest_file instead.
- `delete_file`: Delete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided.
- `list_files`: List all ingested files in the vector database. Returns file paths and chunk counts for each document.
- `status`: Get system status including total documents, total chunks, database size, and configuration information.
- `feedback_pin`: Pin a search result as relevant for a query. Pinned results will be boosted in future searches. Use when a result was particularly helpful.
- `feedback_dismiss`: Dismiss a search result as irrelevant for a query. Dismissed results will be penalized in future searches. Use when a result was unhelpful.
- `feedback_stats`: Get feedback statistics including total events, pinned pairs, and dismissed pairs.

## FAQ

### Does my data stay private?

Yes, everything runs locally by default and your data stays on your machine unless you choose to pull in content from a remote URL.

### How do I set up RAG Vault for Cursor?

You can add it to your ~/.cursor/mcp.json file using the npx command and specifying your BASE_DIR environment variable.

### Can I use RAG Vault as a remote server?

Yes, you can run it in remote mode as an HTTP server to connect remote MCP clients like Claude.ai or Claude Desktop.
