Obsidian Semantic Search#

Search your Obsidian vault by meaning, not just keywords. This skill installs and configures obsidian-semantic-mcp — a local-first MCP server that indexes your vault with vector embeddings (Ollama + pgvector) and exposes 10 tools to any MCP-compatible AI assistant.

What You Get#

10 MCP Tools#

ToolWhat it doessearch_vaultSemantic, keyword, or hybrid search with similarity scoressimple_searchFast exact-text search across all fileslist_filesBrowse vault directoriesget_fileRead a single fileget_files_batchRead multiple files in one callappend_contentAppend text to a file (creates if missing)write_fileOverwrite a file completelyrecent_changesList recently modified fileslist_indexed_notesSee all indexed notes with timestampsreindex_vaultForce a full re-index

Monitoring Dashboard (port 8484)#

• Real-time service health (PostgreSQL, Ollama, embedding model)
• Indexed notes count, vault coverage %, database size
• Search testing UI — test queries without leaving your browser
• Manual re-index trigger

Search Modes#

• Hybrid (default): Combines semantic meaning + keyword matching for best results
• Semantic: Search by meaning only — finds related content even with different wording
• Keyword: Exact text matching via PostgreSQL full-text search

Installation#

Prerequisites#

• Docker Desktop (running)
• uv (Python package manager): curl -LsSf https://astral.sh/uv/install.sh | sh
• An Obsidian vault on your local filesystem

One-Liner Install#

bash

bash <(curl -fsSL https://raw.githubusercontent.com/celstnblacc/obsidian-semantic-mcp/main/install.sh) --mode 2 --vault /path/to/your/vault

This clones the repo to ~/.local/share/obsidian-semantic-mcp, installs the osm CLI, and runs the setup wizard in Docker mode.

Manual Install#

bash

git clone https://github.com/celstnblacc/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
uv sync
uv run osm init

The wizard detects your OS and offers setup modes:

macOS (4 modes):

• Mode 1: Native (Homebrew — no Docker needed)
• Mode 2: Docker + host Ollama (if Ollama already installed)
• Mode 3: Full Docker (recommended — everything in containers)
• Mode 4: Docker + remote Ollama (SSH tunnel to a GPU server)

Linux (3 modes):

• Mode 1: Docker + host Ollama
• Mode 2: Full Docker (recommended)
• Mode 3: Docker + remote Ollama

Verify Installation#

bash

osm status

Should show: Docker containers running, Ollama healthy, embedding model loaded, vault indexed.

Register with Claude Desktop#

The wizard auto-configures this, but if you need to do it manually:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

json

{
  "mcpServers": {
    "obsidian-semantic": {
      "command": "docker",
      "args": ["exec", "-i", "obsidian-semantic-mcp-mcp-server-1", "python3", "src/server.py"]
    }
  }
}

Restart Claude Desktop after adding.

Configuration#

Set these in .env or as environment variables:

VariableRequiredDefaultNotesOBSIDIAN_VAULTYes—Path to your vaultOBSIDIAN_VAULTSNo—Comma-separated paths for multi-vaultPOSTGRES_PASSWORDYes (Docker)—Database passwordEMBEDDING_MODELNonomic-embed-textOllama model (~7GB)RERANK_MODELNo—Optional cross-encoder for better rankingDASHBOARD_PORTNo8484Monitoring dashboard port

Usage Examples#

Once installed, your AI assistant can use these tools naturally:

Semantic search:

"Search my vault for notes about authentication patterns" → Uses search_vault with hybrid mode, returns top 5 matches ranked by meaning

Find and read:

"Find my meeting notes from last week and summarize them" → Uses recent_changes to find files, get_files_batch to read them

Append to a note:

"Add this action item to my project-x.md file" → Uses append_content to add text without overwriting

Re-index after bulk changes:

"I just reorganized my vault, re-index everything" → Uses reindex_vault to rebuild the full index

Maintenance#

bash

osm status       # Check health
osm rebuild      # Rebuild Docker images after updates
osm remove       # Stop and clean up everything

Architecture#

• PostgreSQL 17 + pgvector: Stores 768-dim vector embeddings, IVFFlat index for fast cosine similarity search
• Ollama (nomic-embed-text): Local embedding model — no API keys, no cloud calls
• Watchdog file watcher: Auto-re-indexes when vault files change (0.5s debounce)
• LRU cache: 256 entries, 10-min TTL — skips redundant Ollama calls for repeated queries

Troubleshooting#

ProblemFix"Ollama not responding"Run osm status — if Ollama is down, the dashboard has a "Start Ollama" buttonSlow first searchFirst query loads the model into memory (~5s). Subsequent queries are <1sMissing notes in searchRun osm status to check indexing coverage. Use dashboard to trigger re-indexDocker errorsEnsure Docker Desktop is running. Try osm rebuild to rebuild imagesVirusTotal "suspicious" warning on installThis is a false positive — the skill describes searching vault content, which triggers pattern detection. Use clawhub install obsidian-semantic-search --force to proceed. The skill is MIT-0 licensed and contains no executable code beyond documentation.

Links#

• Source: https://github.com/celstnblacc/obsidian-semantic-mcp
• Changelog: https://github.com/celstnblacc/obsidian-semantic-mcp/blob/main/CHANGELOG.md
• Architecture: https://github.com/celstnblacc/obsidian-semantic-mcp/blob/main/docs/ARCHITECTURE.md
• License: Apache 2.0 (source repo) / MIT-0 (this skill)

---

Built by celstnblacc — 207 unit tests, Docker + native install, multi-vault support.