# Obsidian RAG MCP Server
Semantic search for your Obsidian vault, exposed as an MCP server for Claude Code integration.
## What This Does
Turn your Obsidian vault into a searchable knowledge base that AI assistants can query semantically. Instead of keyword matching, find documents by meaning.
**Example:**
> "Find RCAs where database timeouts caused customer-facing issues"
Returns relevant RCA documents even if they use terms like "CosmosDB latency", "connection pool exhaustion", or "query timeout" — not just exact keyword matches.
## Features
- 🔍 **Semantic Search**: Find documents by meaning, not just keywords
- 🏷️ **Tag-Aware**: Filter searches by Obsidian tags
- 📊 **Metadata Extraction**: Leverages frontmatter and document structure
- 🔌 **MCP Integration**: Works directly with Claude Code
- 🏠 **Local-First**: Your data stays on your machine (only embeddings sent to OpenAI)
- ⚡ **Fast**: Sub-second queries on 100+ document vaults
## Quick Start
### Prerequisites
- Python 3.11+
- OpenAI API key (for embeddings)
- An Obsidian vault (or use the included sample vault)
### Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/obsidian-rag-mcp.git
cd obsidian-rag-mcp
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # or `.venv\Scripts\activate` on Windows
# Install dependencies
pip install -e .
# Set up environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
```
### Index Your Vault
```bash
# Index the sample vault
obsidian-rag index ./vault
# Or index your own vault
obsidian-rag index /path/to/your/obsidian/vault
```
### Test It
```bash
# Search from CLI
obsidian-rag search "database connection issues"
# Start the MCP server
obsidian-rag serve
```
### Connect to Claude Code
Add to your Claude Code MCP configuration:
```json
{
"mcpServers": {
"obsidian-rag": {
"command": "obsidian-rag",
"args": ["serve", "--vault", "/path/to/your/vault"],
"env": {
"OPENAI_API_KEY": "your-key-here"
}
}
}
}
```
## MCP Tools
Once connected, Claude Code has access to these tools:
| Tool | Description |
|------|-------------|
| `search_vault` | Semantic search across all vault content |
| `search_by_tag` | Search filtered by Obsidian tags |
| `get_related` | Find notes related to a given note |
| `get_note` | Retrieve full content of a specific note |
| `list_recent` | List recently modified notes |
## Sample Vault
The `vault/` directory contains sample RCA documents for testing. To regenerate:
```bash
python scripts/seed_vault.py
```
## Architecture
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed system design.
## Development
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Type checking
mypy src
# Linting
ruff check src
```
## Configuration
Environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `OPENAI_API_KEY` | Yes | OpenAI API key for embeddings |
| `OBSIDIAN_VAULT_PATH` | No | Default vault path |
| `CHROMA_PERSIST_DIR` | No | ChromaDB storage location |
## Cost
Embedding costs with OpenAI text-embedding-3-small:
- ~100 notes (avg 2000 tokens each): ~$0.02 per full reindex
- Queries: ~$0.00001 per query
## License
MIT
## Acknowledgments
- [ChromaDB](https://www.trychroma.com/) for the vector database
- [MCP](https://modelcontextprotocol.io/) for the protocol spec
- [OpenAI](https://openai.com/) for embeddings
