obsidian-rag-mcp 0.2.0

Semantic search for Obsidian vaults via MCP

Obsidian RAG MCP Server

Your notes, searchable by meaning.

An MCP server that gives Claude Code semantic search over your Obsidian vault. Ask questions in natural language, get answers from your own documents.

---

The Problem

You have 500 notes in Obsidian. You know you wrote something about database timeouts causing customer issues... somewhere. Ctrl+F won't help when you don't remember the exact words.

The Solution

This server indexes your vault with vector embeddings. Ask for "RCAs where database timeouts caused customer-facing issues" and get results even if your notes use terms like "CosmosDB latency", "connection pool exhaustion", or "query timeout."

Semantic search. Vectors stored locally. Sub-second queries.

---

Quick Start

# Clone and install (using uv - recommended)
git clone https://github.com/danielscholl/obsidian-rag-mcp.git
cd obsidian-rag-mcp
uv sync

# Set your API key
export OPENAI_API_KEY="sk-..."

# Index the sample vault (or your own)
uv run obsidian-rag index --vault ./vault

# Search it
uv run obsidian-rag search "database connection issues" --vault ./vault

Output

Query: database connection issues
Found 3 results (searched 1154 chunks)

--- Result 1 (score: 0.480) ---
Source: RCAs/2025-05-17-database-connection-pool-exhaustion.md
Tags: database, p1, rca

# 2025-05-17 - Database Connection Pool Exhaustion in payment-gateway...

--- Result 2 (score: 0.466) ---
Source: RCAs/2025-06-18-database-connection-pool-exhaustion.md
Tags: database, p2, rca

# 2025-06-18 - Database Connection Pool Exhaustion in auth-service...

---

Connect to Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/obsidian-rag-mcp", "obsidian-rag", "serve"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Then ask Claude things like:

• "Search my vault for notes about Kubernetes deployments"
• "Find RCAs related to authentication failures"
• "What did I write about the Q3 migration?"

---

MCP Tools

Tool	What it does
search_vault	Semantic search across all content
search_by_tag	Filter by Obsidian tags
get_note	Retrieve full note content
get_related	Find notes similar to a given note
list_recent	Recently modified notes
index_status	Index statistics
search_with_reasoning	Search with extracted conclusions
get_conclusion_trace	Trace reasoning for a conclusion
explore_connected_conclusions	Find related conclusions

---

How It Works

1. Index: Scans your vault, chunks markdown intelligently (respecting headers, code blocks), generates embeddings via OpenAI
2. Store: Vectors go into ChromaDB (local, no external database needed)
3. Query: Your question gets embedded, matched against stored vectors, ranked results returned
4. Reasoning (optional): Extract conclusions from notes at index time for richer search results

Documentation:

• Getting Started - 5-minute tutorial with Claude Desktop setup
• Architecture - System design
• Development - Local setup (includes Windows)
• Integration - Use with other agents/pipelines

---

Configuration

Variable	Required	Description
OPENAI_API_KEY	Yes*	For embeddings (and reasoning if enabled)
AZURE_OPENAI_ENDPOINT	No*	Azure OpenAI endpoint URL
AZURE_API_KEY	No*	Azure OpenAI API key
AZURE_OPENAI_VERSION	No	Azure API version (default: 2024-10-21)
AZURE_EMBEDDING_DEPLOYMENT	No	Azure deployment name (default: text-embedding-3-small)
OBSIDIAN_VAULT_PATH	No	Default vault path
REASONING_ENABLED	No	Enable conclusion extraction (default: false)

* Either OPENAI_API_KEY or AZURE_OPENAI_ENDPOINT + AZURE_API_KEY is required. When both Azure variables are set, Azure OpenAI is used automatically.

Cost: ~$0.02 to index 100 notes. Queries are essentially free.

---

Development

uv sync

# Tests
uv run pytest

# Lint + format
uv run black obsidian_rag_mcp/ tests/
uv run ruff check obsidian_rag_mcp/ tests/

See docs/DEVELOPMENT.md for the full guide.

---

Requirements

• Python 3.11+
• OpenAI API key
• An Obsidian vault (or use vault/ for testing)

---

License

MIT

---

Getting Started | Architecture | Development | Integration