alexhholmes/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 package manager

Installation

Install uv (if not already installed)

pip install uv

Install mcp-obsidian

Option 1: Install as a uv tool (Recommended)

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:

git clone https://github.com/yourusername/mcp-obsidian.git
cd mcp-obsidian

2. Create and activate a virtual environment with uv:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the package in development mode:

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:

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:

{
  "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:

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:

# 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):

{
  "mcpServers": {
    "obsidian": {
      "command": "mcp-obsidian"
    }
  }
}

or alternatively use to configuration tool to set it up automatically:

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