Obsidian MCP

A local MCP server that adds semantic search and connection discovery to your Obsidian vault (or any Markdown folder). It uses on-device BERT embeddings — no data leaves your machine.

What it does

Exposes three tools over the Model Context Protocol:

Tool	Description
initialize_session	Index a vault directory and return a session token
semantic_search_live	Search indexed notes by meaning, not just keywords
find_hidden_connections	Surface notes that are semantically related but use different terminology

Prerequisites

• Rust (1.75+) — install via rustup
• The embedding model (sentence-transformers/all-MiniLM-L6-v2) is downloaded automatically from HuggingFace on first run

Build

cargo build --release

The binary lands at target/release/obsidian-mcp.

Setup with Claude Code

Add to your project's .mcp.json (or global ~/.claude/mcp.json):

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "/absolute/path/to/obsidian-mcp/target/release/obsidian-mcp",
      "args": []
    }
  }
}

Replace the path with wherever you built the binary.

Setup with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "/absolute/path/to/obsidian-mcp/target/release/obsidian-mcp"
    }
  }
}

Usage

Once connected, ask Claude to initialize your vault:

"Initialize my Obsidian vault at ~/Documents/MyVault"

Then search or explore connections:

"Search my notes for anything related to distributed consensus"

"Find hidden connections across my vault"

How it works

1. Indexing — walks the vault, splits each Markdown file into chunks by H2/H3 headings, and generates embeddings using a local BERT model
2. Caching — embeddings are cached at ~/.cache/obsidian-mcp/ and reused when files haven't changed
3. Search — computes cosine similarity between your query embedding and all stored chunks
4. Connections — finds chunk pairs with high semantic similarity but low lexical overlap (Jaccard filtering), then clusters them

Architecture

src/
├── main.rs          # entry point — loads model, starts MCP transport
├── server.rs        # MCP tool definitions and handlers
├── session.rs       # vault indexing and session management
├── parser.rs        # Markdown → chunks (H2/H3 splitting)
├── search.rs        # cosine similarity search & connection discovery
├── embeddings.rs    # BERT model loading & batch embedding
├── walker.rs        # vault file traversal
├── cache.rs         # persistent embedding cache
└── error.rs         # error types