obsidian-mcp

A high-performance MCP server that gives AI agents full read/write access to Obsidian vaults. Written in Rust. Ships as a single binary.

No Obsidian plugins. No REST API. No Obsidian running. Just your vault on disk.

Why?

Existing solutions for AI + Obsidian require the Obsidian app to be running with a community plugin (obsidian-local-rest-api) and an MCP wrapper (mcp-obsidian) on top. That's fragile, slow, and limited to what the REST API exposes.

obsidian-mcp talks directly to the filesystem. It understands the Obsidian format natively — wikilinks, frontmatter, tags, block references, periodic notes, the full graph. It builds fast in-memory indices on startup and keeps them synced via a filesystem watcher. The result is a single dependency-free binary that works whether Obsidian is open or not.

Quick Start

# Install
cargo install obsidian-mcp

# Run
obsidian-mcp /path/to/your/vault

Add to your MCP client config (Cursor, Claude Desktop, etc.) and you're done — 29 tools are available immediately.

What It Can Do

All indices (metadata, BM25, embeddings) update in real time via a filesystem watcher.

Installation

From crates.io

cargo install obsidian-mcp

For semantic search local compatibility mode (OBSIDIAN_SEMANTIC_MODE=local), build with embeddings:

cargo install obsidian-mcp --features embeddings

The embeddings feature adds ~60 MB to the binary (ONNX Runtime). In daemon mode, model/runtime cache is shared under semantic home; local mode keeps in-process embedding support in the MCP binary.

Pre-built binaries

Grab the latest from GitHub Releases:

Semantic daemon release assets are also published per target:

• obsidian-semanticd-<version>-<target>.tar.gz (Unix)
• obsidian-semanticd-<version>-<target>.zip (Windows)

Semantic Runtime Compatibility

Current semantic daemon API version: 1 (DAEMON_API_VERSION in src/daemon/protocol.rs).

Release asset compatibility expectations:

• Daemon auto-install clients expect release assets named obsidian-semanticd-<version>-<target>.{tar.gz|zip} plus checksums.sha256.
• Plugin releases should publish main.js, manifest.json, and optional styles.css as GitHub release assets.

Upgrade guidance:

• Prefer upgrading obsidian-mcp, obsidian-semanticd, and obsidian-semantic-search-plugin together.
• If versions are skewed, startup/handshake fails with explicit API incompatibility errors rather than silent fallback.

Client Setup

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "args": ["/path/to/your/vault"]
    }
  }
}

Claude Desktop

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

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Any MCP client

obsidian-mcp communicates over stdio using the standard MCP JSON-RPC protocol. Any client that supports MCP stdio transport will work. Pass the vault path as the first argument or via OBSIDIAN_VAULT_PATH.

Search

Three tiers, each suited to different needs.

BM25 Full-Text — search_text

On by default. Powered by Tantivy, rebuilt in-memory on startup (< 100 ms for 5k notes).

• Stemming — "deploy" matches "deployment", "deployed", "deploying"
• Field boosts — title 5x, tags 4x, headings 3x, frontmatter 2x, body 1x
• Fuzzy matching — fuzzy: true tolerates single-character typos (edit distance 1)
• Field filtering — fields: ["title", "tags"] to restrict scope
• Returns ranked results with context snippets and match offsets

Semantic — search_semantic

Uses the shared local semantic daemon by default (OBSIDIAN_SEMANTIC_MODE=auto). Results keep the same MCP schema while backend execution can run through daemon or local compatibility mode.

Semantic runtime modes:

• auto (default): prefer daemon, fallback to local in-process embeddings when daemon is unavailable and local embeddings are enabled.
• daemon: daemon-only path; semantic calls fail clearly if daemon is unavailable.
• local: force legacy in-process embeddings path.

Daemon startup policy:

• MCP only initializes/starts the daemon when OBSIDIAN_WATCH=true.

• When OBSIDIAN_WATCH=false, MCP skips daemon initialization and semantic search must use local mode (if enabled) or returns a clear error.

• Finds notes by meaning, not keywords — "making money from software" surfaces notes about monetization

• Hybrid mode — lexical_prefetch: true combines BM25 candidate retrieval with semantic re-ranking

• Tunable blending — alpha controls the weight between lexical and semantic scores (default 0.25)

• Daemon cache migration is one-way and non-destructive: legacy .obsidian/obsidian-mcp/embeddings.bin is copied into daemon namespace store when available, and never deleted automatically

Regex — search_regex

Always available. Full regex syntax for pattern matching across all notes.

When to Use What

Tool Reference

Navigation

Note CRUD

Search

Metadata & Frontmatter

Graph & Links

Periodic Notes

Utility

Configuration

* Also accepted as the first CLI argument: obsidian-mcp /path/to/vault

Architecture

AI Client (Cursor, Claude Desktop, etc.)
 │ stdio (MCP JSON-RPC)
 ▼
obsidian-mcp
 ├─ tools/          MCP handlers — translate protocol into vault ops
 ├─ vault/
 │  ├─ index        In-memory metadata (tags, links, headings)
 │  ├─ tantivy      BM25 full-text search
 │  ├─ embeddings   Semantic vectors (optional)
 │  └─ watcher      Filesystem events → index sync
 ├─ models.rs       Shared types
 └─ error.rs        VaultError → MCP ErrorData
 │ fs
 ▼
Vault directory (.md files + .obsidian/)

The vault layer is a pure Rust library with no knowledge of MCP. The tools layer is a thin adapter. This separation means the vault code is independently testable and reusable.

Development

cargo build                          # default build
cargo build --features embeddings    # with semantic search

OBSIDIAN_VAULT_PATH=~/vault cargo run
OBSIDIAN_VAULT_PATH=~/vault OBSIDIAN_EMBEDDINGS=true cargo run --features embeddings

cargo fmt --check && cargo clippy && cargo test

npx @modelcontextprotocol/inspector cargo run   # interactive testing

License

MIT