Obsidian Semantic Search — Obsidian Semantic 搜索

Obsidian Semantic 搜索

搜索 your Obsidian vault by meaning, not just keywords. This 技能 安装s and 配置s obsidian-semantic-mcp — a local-first MCP server that 索引es your vault with vector embeddings (Ollama + pgvector) and exposes 10 工具s to any MCP-compatible AI 助手.

What You 获取 10 MCP 工具s 工具 What it does 搜索_vault Semantic, keyword, or hybrid 搜索 with similarity scores simple_搜索 Fast exact-text 搜索 across all files 列出_files Browse vault directories 获取_file Read a single file 获取_files_batch Read multiple files in one call 应用end_content 应用end text to a file (创建s if missing) write_file Overwrite a file completely recent_changes 列出 recently modified files 列出_索引ed_notes See all 索引ed notes with timestamps re索引_vault Force a full re-索引 监控ing 仪表盘 (port 8484) Real-time 服务 健康 (PostgreSQL, Ollama, embedding 模型) 索引ed notes count, vault coverage %, database size 搜索 测试 UI — test queries without leaving your browser Manual re-索引 trigger 搜索 Modes Hybrid (default): Combines semantic meaning + keyword matching for best 结果s Semantic: 搜索 by meaning only — finds related content even with different wording Keyword: Exact text matching via PostgreSQL full-text 搜索 安装ation Prerequisites Docker 桌面 (运行ning) uv (Python package 管理器): curl -LsSf https://astral.sh/uv/安装.sh | sh An Obsidian vault on your local file系统 One-Liner 安装 bash <(curl -fsSL https://raw.githubusercontent.com/celstnblacc/obsidian-semantic-mcp/mAIn/安装.sh) --mode 2 --vault /path/to/your/vault

This clones the repo to ~/.local/分享/obsidian-semantic-mcp, 安装s the osm 命令行工具, and 运行s the 设置up wizard in Docker mode.

Manual 安装 git clone https://github.com/celstnblacc/obsidian-semantic-mcp.git cd obsidian-semantic-mcp uv 同步 uv 运行 osm init

The wizard 检测s your OS and offers 设置up modes:

macOS (4 modes):

Mode 1: Native (Homebrew — no Docker needed) Mode 2: Docker + host Ollama (if Ollama already 安装ed) 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 验证 安装ation osm 状态

Should show: Docker contAIners 运行ning, Ollama 健康y, embedding 模型 loaded, vault 索引ed.

Register with Claude 桌面

The wizard auto-配置s this, but if you need to do it manually:

添加 to ~/库/应用 Support/Claude/claude_桌面_config.json (macOS) or ~/.config/Claude/claude_桌面_config.json (Linux):

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

Re启动 Claude 桌面 after 添加ing.

Configuration

设置 these in .env or as 环境 variables:

Variable Required Default Notes OBSIDIAN_VAULT Yes — Path to your vault OBSIDIAN_VAULTS No — Comma-separated paths for multi-vault POSTGRES_PASSWORD Yes (Docker) — Database password EMBEDDING_模型 No nomic-embed-text Ollama 模型 (~7GB) RERANK_模型 No — Optional cross-encoder for better ranking 仪表盘_PORT No 8484 监控ing 仪表盘 port Usage Examples

Once 安装ed, your AI 助手 can use these 工具s naturally:

Semantic 搜索:

"搜索 my vault for notes about authentication patterns" → Uses 搜索_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, 获取_files_batch to read them

应用end to a note:

"添加 this action item to my project-x.md file" → Uses 应用end_content to 添加 text without overwriting

Re-索引 after bulk changes:

"I just reorganized my vault, re-索引 everything" → Uses re索引_vault to rebuild the full 索引

MAIntenance osm 状态 # 检查 健康 osm rebuild # Rebuild Docker images after 更新s osm 移除 # 停止 and 清理 up everything

Architecture PostgreSQL 17 + pgvector: Stores 768-dim vector embeddings, IVFFlat 索引 for fast cosine similarity 搜索 Ollama (nomic-embed-text): Local embedding 模型 — no API keys, no cloud calls Watchdog file watcher: Auto-re-索引es when vault files change (0.5s debounce) LRU 缓存: 256 entries, 10-min TTL — skips redundant Ollama calls for repeated queries Troubleshooting Problem Fix "Ollama not 响应ing" 运行 osm 状态 — if Ollama is down, the 仪表盘 has a "启动 Ollama" button Slow first 搜索 First 查询 loads the 模型 into memory (~5s). Subsequent queries are <1s Missing notes in 搜索 运行 osm 状态 to 检查 索引ing coverage. Use 仪表盘 to trigger re-索引 Docker errors Ensure Docker 桌面 is 运行ning. Try osm rebuild to rebuild images VirusTotal "suspicious" 警告 on 安装 This is a false positive — the 技能 describes 搜索ing vault content, which triggers pattern 检测ion. Use ClawHub 安装 obsidi