MCP Obsidian

# mcp-obsidian An MCP (Model Context Protocol) server for semantic search in Obsidian vaults using embedded ChromaDB vector storage. I intend on keeping this fairly minimal to keep usage with Claude simple. ## Features - 🔍 **Search** with semantic, exact phrase, and temporal filtering - 📝 **Google-style quotes** for exact phrase matching (`"exact phrase"` and `-"exclude"`) - 📅 **Date filtering** to find notes by modification time - 📁 Support for multiple vault configurations - 🔄 **Real-time monitoring** with automatic re-indexing - 🚀 Fast, incremental updates with ChromaDB backend - 🔒 Thread-safe operations for concurrent access ## Prerequisites - Python 3.10 or higher - [uv](https://github.com/astral-sh/uv) package manager ## Installation ### Install uv (if not already installed) ```bash pip install uv ``` ### Install mcp-obsidian #### Option 1: Install as a uv tool (Recommended) ```bash uv tool install "git+https://github.com/alexhholmes/mcp-obsidian.git" mcp-obsidian configure # Configure your vaults ``` #### Option 2: Install from source 1. Clone the repository: ```bash git clone https://github.com/yourusername/mcp-obsidian.git cd mcp-obsidian ``` 2. Create and activate a virtual environment with uv: ```bash uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` 3. Install the package in development mode: ```bash uv pip install -e . ``` This will install all dependencies including: - questionary (interactive CLI) - chromadb (vector database) - langchain-text-splitters (document chunking) - fastmcp (MCP server framework) - watchdog (file system monitoring) ## Configuration ### Initial Setup Configure your Obsidian vaults: ```bash mcp-obsidian configure ``` This interactive command will: 1. Prompt you to select vault directories 2. Name each vault for easy reference 3. Store configuration in `~/.mcp-obsidian/config.json` ### Manual Configuration You can also manually edit `~/.mcp-obsidian/config.json`: ```json { "vaults": [ { "name": "Personal Notes", "path": "/path/to/your/obsidian/vault" }, { "name": "Work Docs", "path": "/path/to/another/vault" } ] } ``` ## Usage ### As an MCP Server Run the server for use with MCP-compatible clients: ```bash mcp-obsidian ``` The server exposes the following tools: - `search`: Unified search with semantic, exact phrase, and temporal filtering - `reindex_vaults`: Manually trigger a re-index of all configured vaults The vectors are stored along with the following metadata, which can be used for filtering searches: - `vault`: The name of the vault containing the document - `title`: The filename without extension - `source`: The relative path from the vault root - `modified`: Unix timestamp of the file's last modification time - `file_path`: The absolute path to the source file - `start_line` / `end_line`: Line numbers for the chunk within the original document - `chunk_index` / `total_chunks`: Position of this chunk within the document - `file_hash`: MD5 hash of the file content for change detection ### CLI Usage Search directly from the command line: ```bash # Search all vaults mcp-obsidian search "your search query" # Search a specific vault mcp-obsidian search "your search query" --vault "Personal Notes" # Reconfigure vaults mcp-obsidian configure # Rebuild search index mcp-obsidian index ``` ### Integration with Claude Desktop Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "obsidian": { "command": "mcp-obsidian" } } } ``` or alternatively use to configuration tool to set it up automatically: ```bash mcp-obsidian configure ``` ## How It Works 1. **Indexing**: The server reads all markdown files from configured vaults and creates vector embeddings using ChromaDB 2. **Chunking**: Large documents are split into smaller chunks using recursive character splitting for better search granularity 3. **Search**: Queries are converted to embeddings and matched against the document database using cosine similarity 4. **File Watching**: The server monitors vault directories for changes and automatically updates the index ## License MIT License