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 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

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_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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

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

obsidian-mcp
StevenStavrakis
-
security
A
license
-
quality
Enables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.
Last updated -
276
482
TypeScript
MIT License
Obsidian MCP REST Server
PublikPrinciple
-
security
A
license
-
quality
Provides 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 -
52
TypeScript
MIT License
Obsidian MCP
takuya0206
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.
Last updated -
5
276
2
TypeScript
ISC License
MCP Obsidian
gregkonush
-
security
A
license
-
quality
A server implementation that allows AI assistants to read, create, and manipulate notes in Obsidian vaults through the Model Context Protocol.
Last updated -
930
5
TypeScript
MIT License

View all related MCP servers

Appeared in Searches

Information about Obsidian