Obsidian MCP Server

How to use

Start the server locally and connect your MCP client to it. The server exposes a single local, stdio‑based MCP endpoint named obsidian. You run the server as a normal process and let your client communicate via the MCP protocol over standard input/output.

Typical workflow patterns you will use: search notes by full‑text query with optional tag filters, retrieve full note content, list recently changed notes, and enumerate or filter by tags. The server keeps the index up to date automatically and supports incremental updates for large vaults.

How to install

Prerequisites: Python is installed on your system and you have a shell available. You will also need access to your Obsidian vault on disk.

Option A: Local installation (Python package)

# Install the MCP server package in editable mode
pip install -e .

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

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

# For reproducible installs (optional, requires uv)
uv pip sync requirements.lock
uv pip sync requirements-dev.lock

Option B: Docker (if you prefer containerized runtime)

# Build the image
docker build -t obsidian-mcp-server .

# Run the container (example, adjust paths as needed)
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

Optionally, you can use Docker Compose and edit the docker-compose.yml to set your vault path, then start the services in the background with docker-compose up -d.

Environment setup example (required): you must point the server at your vault location.

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

Additional configuration and usage notes

Optional environment variables customize behavior and performance. These are the variables you can set to tailor the server to your environment.

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)

Troubleshooting and tips

If results seem stale, the index can be rebuilt automatically on startup, or you can delete the index directory to force a complete rebuild. Ensure the server has read access to the vault. For large vaults, enabling incremental updates and tag filtering can improve query performance.

Multi‑machine usage helps you keep local copies in sync while each machine maintains its own optimized index. Real‑time updates and incremental indexing work across machines, so you can keep search fast even when vaults are synchronized via Obsidian Sync, iCloud, Dropbox, or Git.

Tools and endpoints

The MCP server provides a set of endpoints to search notes, fetch content, and query metadata. These tools enable you to build powerful assistants that can retrieve information from your vault with minimal latency.

search_notes

Search through notes by a full‑text query with optional tag filtering and limit on results.

get_note

Retrieve the full content of a note by its identifier.

list_recent_notes

List recently modified notes up to a specified limit.

get_all_tags

List all tags present in the vault.

search_by_tag

Find notes that contain specific tags with an optional limit on results.

get_vault_stats

Provide statistics about the vault and the search index.