-
securityA
license-
qualityEnables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.
Last updated -
903
532
MIT License
Offers containerized deployment option with volume mounting for Obsidian vaults and persistent index storage.
Supports multi-machine usage with Obsidian vaults synced through Dropbox, maintaining separate optimized indexes on each machine.
Supports multi-machine usage with Obsidian vaults synced through git, maintaining separate optimized indexes on each machine.
Supports multi-machine usage with Obsidian vaults synced through iCloud, maintaining separate optimized indexes on each machine.
Provides full-text search access to Obsidian vaults, including tag-based filtering, frontmatter support, wikilink parsing, and real-time updates without requiring Obsidian plugins.
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]]syntaxReal-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 wikilinksSearch Index (
search.py): Whoosh-based full-text search with metadata supportFile Watcher (
watcher.py): Monitors vault for changes and updates index incrementallyMCP Server (
server.py): Implements the Model Context Protocol interfaceConfiguration (
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 queriesUsing more specific search terms
Filtering by tags to narrow results
Incremental updates are especially beneficial for large vaults
License
MIT License
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Provides AI assistants with full-text search access to your Obsidian vault, allowing them to query, retrieve, and analyze notes through the Model Context Protocol.
Related MCP Servers
- -securityAlicense-qualityProvides a standardized interface for AI assistants to interact with Obsidian vaults through a local REST API, enabling reading, writing, searching, and managing notes.Last updated -58MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.Last updated -59032ISC License
- -securityAlicense-qualityA server implementation that allows AI assistants to read, create, and manipulate notes in Obsidian vaults through the Model Context Protocol.Last updated -7085MIT License