Obsidian MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with full-text search access to your Obsidian vault.

Features

• Full-text search across all notes using Whoosh search engine
• Tag-based filtering and search
• Frontmatter support - extracts and indexes YAML metadata
• Wikilink parsing - understands Obsidian's [[note]] syntax
• Real-time updates - watches vault for changes and updates index automatically
• No Obsidian plugins required - works directly with filesystem
• Fast and efficient - pure Python implementation with optimized indexing

Installation

Option 1: Local Installation

1. Clone this repository:

git clone <repository-url>
cd obsidianMCP

2. Install dependencies:

# Basic installation
pip install -e .

# Or install from requirements
pip install -r requirements.txt

# For development (includes testing tools)
pip install -r requirements-dev.txt
# OR
pip install -e ".[dev]"

# For reproducible installs using lock files (requires uv)
uv pip sync requirements.lock              # Production dependencies only
uv pip sync requirements-dev.lock          # With development dependencies

Option 2: Docker

1. Clone this repository:

git clone <repository-url>
cd obsidianMCP

2. Build the Docker image:

docker build -t obsidian-mcp-server .

3. Run with Docker:

docker run -it --rm \
  -e OBSIDIAN_VAULT_PATH=/vault \
  -v /path/to/your/obsidian/vault:/vault:ro \
  -v obsidian-index:/app/index \
  obsidian-mcp-server

Or use Docker Compose:

# Edit docker-compose.yml to set your vault path
docker-compose up -d

Usage

Environment Setup

Set the required environment variable:

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

Optional environment variables:

export OBSIDIAN_INDEX_PATH="/path/to/index"  # Default: vault/.obsidian-mcp-index
export OBSIDIAN_MAX_RESULTS=50               # Default: 50
export OBSIDIAN_AUTO_REBUILD_INDEX=true      # Default: true
export OBSIDIAN_INCREMENTAL_UPDATE=true      # Default: true
export OBSIDIAN_WATCH_CHANGES=true           # Default: true
export OBSIDIAN_INCLUDE_CONTENT=true         # Default: true
export OBSIDIAN_USE_POLLING_OBSERVER=false   # Default: false (set to true for Docker/network drives)

Running the Server

obsidian-mcp-server

Or with command line arguments:

obsidian-mcp-server --vault-path /path/to/vault --max-results 100

Claude Desktop Integration

Local Installation

Add to your Claude Desktop configuration (~/.config/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Docker Integration

For Docker, you'll need to create a wrapper script since Claude Desktop needs to communicate via stdio. Create a script like:

#!/bin/bash
# obsidian-mcp-docker.sh
docker run -i --rm \
  -e OBSIDIAN_VAULT_PATH=/vault \
  -v /path/to/your/obsidian/vault:/vault:ro \
  -v obsidian-index:/app/index \
  obsidian-mcp-server

Then configure Claude Desktop to use this script:

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obsidian-mcp-docker.sh"
    }
  }
}

Available Tools

search_notes

Search through your notes using full-text search.

Parameters:

• query (required): Search query string
• tags (optional): Array of tags to filter by
• limit (optional): Maximum results (default: 10)

get_note

Retrieve the full content of a specific note.

Parameters:

• identifier (required): Note path or title

list_recent_notes

Get recently modified notes.

Parameters:

• limit (optional): Maximum results (default: 10)

get_all_tags

List all available tags in the vault.

search_by_tag

Find notes with specific tags.

Parameters:

• tags (required): Array of tags to search for
• limit (optional): Maximum results (default: 20)

get_vault_stats

Get statistics about the vault and search index.

Architecture

• Parser (parser.py): Parses markdown files and extracts frontmatter, tags, and wikilinks
• Search Index (search.py): Whoosh-based full-text search with metadata support
• File Watcher (watcher.py): Monitors vault for changes and updates index incrementally
• MCP Server (server.py): Implements the Model Context Protocol interface
• Configuration (config.py): Handles configuration from environment variables

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/obsidian_mcp

# Generate HTML coverage report
pytest --cov=src/obsidian_mcp --cov-report=html

# Run specific test file
pytest tests/test_parser.py

Code Formatting

black src/
isort src/

Type Checking

mypy src/

Multi-Machine Usage

Perfect for users who sync vaults across multiple machines!

Intelligent Index Updates

• Incremental updates: Only re-indexes files that have changed since last run
• Fast startup: Skips full rebuild when vault hasn't changed
• Cross-machine sync: Works with Obsidian Sync, iCloud, Dropbox, git, etc.

How It Works

1. First run: Builds complete search index
2. Subsequent runs: Compares file modification times
3. Only updates changed files: Fast startup even with large vaults
4. Handles file moves/renames: Maintains search accuracy

Configuration for Multi-Machine

# Recommended settings for synced vaults
export OBSIDIAN_INCREMENTAL_UPDATE=true    # Enable smart updates
export OBSIDIAN_AUTO_REBUILD_INDEX=true    # Auto-rebuild if needed
export OBSIDIAN_WATCH_CHANGES=true         # Real-time updates while running

Troubleshooting

Index Issues

If search results seem outdated, the server automatically rebuilds the index on startup. You can also delete the index directory to force a complete rebuild.

Multi-Machine Sync

• Index files are local to each machine (not synced)
• Vault content is synced between machines
• Each machine maintains its own optimized index

Permission Issues

Ensure the server has read access to your Obsidian vault directory.

Performance

For large vaults (>10,000 notes), consider:

• Reducing max_results for faster queries
• Using more specific search terms
• Filtering by tags to narrow results
• Incremental updates are especially beneficial for large vaults

License

MIT License