obsidian-semantic-search（Obsidian semantic 搜索）

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

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

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

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

{
  "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:

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

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

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