vault-rag-mcp

MCP server for semantic search in an Obsidian Second Brain vault, using a self-hosted Qdrant vector store and Google Gemini embeddings.

Architecture

Claude Code <-> vault-rag MCP server (stdio)
                 |-> Google Gemini gemini-embedding-001 (native 3072d)
                 |-> Qdrant `vault_chunks` collection (3072d, Cosine distance)

Part of a hybrid RAG architecture:

• Indexation: n8n (remote) + Google Gemini API

• Local queries: This MCP server + Google Gemini API

• Web chat: n8n Vault Chat (AI Agent + Gemini native) or Chat Hub (HTTP pipeline)

• Bulk index: Script using Gemini gemini-embedding-001

Same model (gemini-embedding-001, native 3072d) everywhere ensures vector compatibility. Vectors are stored at native 3072 dimensions (float32) with Cosine distance.

Asymmetric task types: RETRIEVAL_DOCUMENT for indexing, RETRIEVAL_QUERY for search.

Related MCP server: mcp-obsidian-local

Tools

Prerequisites

• Python >= 3.11

• uv package manager

• Google API key (for Gemini embeddings)

• Qdrant instance with a vault_chunks collection (created automatically on first index)

Setup

# Clone and install
cd ~/Projects/vault-rag-mcp
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your Google API key and Qdrant credentials

Environment variables

Usage

As MCP server (Claude Code)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "vault-rag": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vault-rag-mcp", "vault-rag-mcp"],
      "env": {
        "QDRANT_URL": "https://your-qdrant-instance.example.com",
        "QDRANT_API_KEY": "your-qdrant-api-key",
        "GOOGLE_API_KEY": "your-google-api-key",
        "EMBEDDING_MODEL": "gemini-embedding-001"
      }
    }
  }
}

Restart Claude Code to activate. Then use the tools directly in conversation.

Bulk indexation

Script to index an entire Obsidian vault via Google Gemini:

uv run python scripts/bulk_index.py /path/to/vault [--force]

Options:

• --force : Re-index all files, ignoring file_hash cache

The script:

1. Walks the vault, skips .obsidian/, templates/, .trash/, files > 500 KB

2. Parses YAML frontmatter (type, tags, PARA folder)

3. Chunks by H2 sections, splits oversized chunks (> 2000 chars)

4. Embeds via Google Gemini in batches of 50 (task_type=RETRIEVAL_DOCUMENT)

5. Upserts to Qdrant with a SHA256 file_hash payload for incremental re-runs

After initial bulk indexation, incremental updates are handled by n8n via Gemini API.

Project structure

vault-rag-mcp/
├── pyproject.toml              # uv + hatch build config
├── .env.example                # Environment template
├── src/
│   └── vault_rag_mcp/
│       ├── __init__.py
│       ├── server.py           # MCP server (FastMCP, stdio) — 3 tools
│       ├── embeddings.py       # Google Gemini embedding client (native 3072d)
│       └── qdrant_store.py     # Qdrant client + collection operations
├── scripts/
│   └── bulk_index.py           # Bulk indexation via Google Gemini
└── n8n-workflows/              # n8n workflow definitions
    ├── vault-rag-github-indexation.json
    └── vault-rag-chat-hub.json

Qdrant collection

Collection vault_chunks — vectors at 3072 dimensions, Cosine distance. Each point carries:

• content — chunk text

• file_path — relative path from vault root

• chunk_index — position within file

• para_folder — PARA folder (1_Projects, 2_Areas, etc.)

• note_type — frontmatter type (memo, glossary, howto, etc.)

• file_hash — SHA256 for change detection

• metadata — tags, type, para_folder

Point IDs are deterministic UUID5 values derived from file_path::chunk_index.

Payload indexes: file_path (keyword), para_folder (keyword), note_type (keyword), chunk_index (integer).

Tech stack

• MCP SDK: mcp[cli] with FastMCP (stdio transport)

• Embeddings: Google Gemini gemini-embedding-001 via the google-genai SDK (native 3072d, multilingual, 2048 token/text)

• Vector DB: Qdrant (self-hosted) — vault_chunks collection, 3072d Cosine distance

• Build: uv + hatch