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
| Tool | What it does |
|---|
| INLINECODE0 | Semantic, keyword, or hybrid search with similarity scores |
| INLINECODE1 |
Fast exact-text search across all files |
|
list_files | Browse vault directories |
|
get_file | Read a single file |
|
get_files_batch | Read multiple files in one call |
|
append_content | Append text to a file (creates if missing) |
|
write_file | Overwrite a file completely |
|
recent_changes | List recently modified files |
|
list_indexed_notes | See all indexed notes with timestamps |
|
reindex_vault | Force 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): INLINECODE10
- An Obsidian vault on your local filesystem
One-Liner Install
CODEBLOCK0
This clones the repo to ~/.local/share/obsidian-semantic-mcp, installs the osm CLI, and runs the setup wizard in Docker mode.
Manual Install
CODEBLOCK1
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
CODEBLOCK2
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):
CODEBLOCK3
Restart Claude Desktop after adding.
Configuration
Set these in .env or as environment variables:
| Variable | Required | Default | Notes |
|---|
| INLINECODE16 | Yes | — | Path to your vault |
| INLINECODE17 |
No | — | Comma-separated paths for multi-vault |
|
POSTGRES_PASSWORD | Yes (Docker) | — | Database password |
|
EMBEDDING_MODEL | No |
nomic-embed-text | Ollama model (~7GB) |
|
RERANK_MODEL | No | — | Optional cross-encoder for better ranking |
|
DASHBOARD_PORT | No |
8484 | Monitoring 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
CODEBLOCK4
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
| Problem | Fix |
|---|
| "Ollama not responding" | Run osm status — if Ollama is down, the dashboard has a "Start Ollama" button |
| Slow first search |
First query loads the model into memory (~5s). Subsequent queries are <1s |
| Missing notes in search | Run
osm status to check indexing coverage. Use dashboard to trigger re-index |
| Docker errors | Ensure Docker Desktop is running. Try
osm rebuild to rebuild images |
| VirusTotal "suspicious" warning on install | This 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.Obsidian 语义搜索
通过含义（而非仅关键词）搜索你的 Obsidian 知识库。此技能安装并配置 obsidian-semantic-mcp——一个本地优先的 MCP 服务器，使用向量嵌入（Ollama + pgvector）为你的知识库建立索引，并向任何兼容 MCP 的 AI 助手开放 10 个工具。
你将获得
10 个 MCP 工具
| 工具 | 功能 |
|---|
| searchvault | 语义搜索、关键词搜索或混合搜索，附带相似度评分 |
| simplesearch |
跨所有文件进行快速精确文本搜索 |
| list_files | 浏览知识库目录 |
| get_file | 读取单个文件 |
| get
filesbatch | 单次调用读取多个文件 |
| append_content | 向文件追加文本（文件不存在则创建） |
| write_file | 完全覆盖文件 |
| recent_changes | 列出最近修改的文件 |
| list
indexednotes | 查看所有已索引笔记及其时间戳 |
| reindex_vault | 强制完全重新索引 |
监控仪表盘（端口 8484）
- - 实时服务健康状态（PostgreSQL、Ollama、嵌入模型）
- 已索引笔记数量、知识库覆盖率%、数据库大小
- 搜索测试界面——无需离开浏览器即可测试查询
- 手动重新索引触发
搜索模式
- - 混合模式（默认）：结合语义含义 + 关键词匹配，获得最佳结果
- 语义模式：仅按含义搜索——即使措辞不同也能找到相关内容
- 关键词模式：通过 PostgreSQL 全文搜索进行精确文本匹配
安装
前置条件
- - Docker Desktop（正在运行）
- uv（Python 包管理器）：curl -LsSf https://astral.sh/uv/install.sh | sh
- 本地文件系统上的 Obsidian 知识库
一行命令安装
bash
bash <(curl -fsSL https://raw.githubusercontent.com/celstnblacc/obsidian-semantic-mcp/main/install.sh) --mode 2 --vault /path/to/your/vault
此命令将仓库克隆到 ~/.local/share/obsidian-semantic-mcp，安装 osm 命令行工具，并在 Docker 模式下运行设置向导。
手动安装
bash
git clone https://github.com/celstnblacc/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
uv sync
uv run osm init
向导会检测你的操作系统并提供设置模式：
macOS（4 种模式）：
- - 模式 1： 原生模式（Homebrew——无需 Docker）
- 模式 2： Docker + 宿主机 Ollama（如果已安装 Ollama）
- 模式 3： 完全 Docker（推荐——所有组件在容器中运行）
- 模式 4： Docker + 远程 Ollama（通过 SSH 隧道连接到 GPU 服务器）
Linux（3 种模式）：
- - 模式 1： Docker + 宿主机 Ollama
- 模式 2： 完全 Docker（推荐）
- 模式 3： Docker + 远程 Ollama
验证安装
bash
osm status
应显示：Docker 容器正在运行、Ollama 健康、嵌入模型已加载、知识库已索引。
注册到 Claude Desktop
向导会自动配置此项，但如果需要手动操作：
添加到 ~/Library/Application Support/Claude/claudedesktopconfig.json（macOS）或 ~/.config/Claude/claudedesktopconfig.json（Linux）：
json
{
mcpServers: {
obsidian-semantic: {
command: docker,
args: [exec, -i, obsidian-semantic-mcp-mcp-server-1, python3, src/server.py]
}
}
}
添加后重启 Claude Desktop。
配置
在 .env 文件或环境变量中设置以下内容：
| 变量 | 是否必需 | 默认值 | 说明 |
|---|
| OBSIDIANVAULT | 是 | — | 知识库路径 |
| OBSIDIANVAULTS |
否 | — | 多知识库的逗号分隔路径 |
| POSTGRES_PASSWORD | 是（Docker） | — | 数据库密码 |
| EMBEDDING_MODEL | 否 | nomic-embed-text | Ollama 模型（约 7GB） |
| RERANK_MODEL | 否 | — | 可选交叉编码器，用于更好的排序 |
| DASHBOARD_PORT | 否 | 8484 | 监控仪表盘端口 |
使用示例
安装完成后，你的 AI 助手可以自然地使用这些工具：
语义搜索：
在我的知识库中搜索关于认证模式的笔记
→ 使用 search_vault 的混合模式，返回按含义排序的前 5 个匹配项
查找并阅读：
找到我上周的会议笔记并总结它们
→ 使用 recentchanges 查找文件，getfiles_batch 读取文件
追加到笔记：
将这条待办事项添加到我的 project-x.md 文件中
→ 使用 append_content 追加文本而不覆盖
批量更改后重新索引：
我刚重新整理了知识库，重新索引所有内容
→ 使用 reindex_vault 重建完整索引
维护
bash
osm status # 检查健康状态
osm rebuild # 更新后重建 Docker 镜像
osm remove # 停止并清理所有内容
架构
- - PostgreSQL 17 + pgvector：存储 768 维向量嵌入，IVFFlat 索引用于快速余弦相似度搜索
- Ollama（nomic-embed-text）：本地嵌入模型——无需 API 密钥，无需云端调用
- Watchdog 文件监视器：知识库文件变化时自动重新索引（0.5 秒防抖）
- LRU 缓存：256 个条目，10 分钟 TTL——对重复查询跳过冗余的 Ollama 调用
故障排除
| 问题 | 解决方法 |
|---|
| Ollama 无响应 | 运行 osm status——如果 Ollama 宕机，仪表盘上有启动 Ollama按钮 |
| 首次搜索缓慢 |
首次查询将模型加载到内存（约 5 秒）。后续查询 <1 秒 |
| 搜索中缺少笔记 | 运行 osm status 检查索引覆盖率。使用仪表盘触发重新索引 |
| Docker 错误 | 确保 Docker Desktop 正在运行。尝试 osm rebuild 重建镜像 |
| 安装时 VirusTotal 显示可疑警告 | 这是误报——该技能
描述了搜索知识库内容，触发了模式检测。使用 clawhub install obsidian-semantic-search --force 继续安装。该技能采用 MIT-0 许可证，除文档外不包含任何可执行代码。 |
链接
- - 源代码： https://github.com/celstnblacc/obsidian-semantic-mcp
- 更新日志： https://github.com/celstnblacc/obsidian-semantic-mcp/blob/main/CHANGELOG.md
- 架构文档： https://github.com/celstnblacc/obsidian-semantic-mcp/blob/main/docs/ARCHITECTURE.md
- 许可证： Apache 2.0（源代码仓库）/ MIT-0（此技能）
由 celstnblacc 构建——207 个单元测试，支持 Docker 和原生安装，多知识库支持。
