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
- Clone this repository:
git clone <repository-url>
cd obsidianMCP
- 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
- Clone this repository:
git clone <repository-url>
cd obsidianMCP
- Build the Docker image:
docker build -t obsidian-mcp-server .
- 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 stringtags(optional): Array of tags to filter bylimit(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 forlimit(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
- First run: Builds complete search index
- Subsequent runs: Compares file modification times
- Only updates changed files: Fast startup even with large vaults
- 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_resultsfor faster queries - Using more specific search terms
- Filtering by tags to narrow results
- Incremental updates are especially beneficial for large vaults
License
MIT License