Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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<details> <summary>Output</summary>
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...</details>
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
- Index: Scans your vault, chunks markdown intelligently (respecting headers, code blocks), generates embeddings via OpenAI
- Store: Vectors go into ChromaDB (local, no external database needed)
- Query: Your question gets embedded, matched against stored vectors, ranked results returned
- Reasoning (optional): Extract conclusions from notes at index time for richer search results
Documentation:
- [Getting Started](docs/GETTING_STARTED.md) - 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
<div align="center">
Getting Started | Architecture | Development | Integration
</div>