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)

Install mcp-obsidian

Option 1: Install as a uv tool (Recommended)

Option 2: Install from source

1. Clone the repository:

2. Create and activate a virtual environment with uv:

3. Install the package in development mode:

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:

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:

Usage

As an MCP Server

Run the server for use with MCP-compatible clients:

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:

Integration with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

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