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.
| Tool | What it does |
|---|---|
| ------ | ------------- |
search_vault | Semantic, keyword, or hybrid search with similarity scores |
simple_search | 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 |
curl -LsSf https://astral.sh/uv/install.sh | shbash <(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.
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):
Linux (3 modes):
osm status
Should show: Docker containers running, Ollama healthy, embedding model loaded, vault indexed.
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.
Set these in .env or as environment 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_MODEL | No | nomic-embed-text | Ollama model (~7GB) |
RERANK_MODEL | No | — | Optional cross-encoder for better ranking |
DASHBOARD_PORT | No | 8484 | Monitoring dashboard port |
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
osm status # Check health
osm rebuild # Rebuild Docker images after updates
osm remove # Stop and clean up everything
| 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. |
Built by celstnblacc — 207 unit tests, Docker + native install, multi-vault support.
共 1 个版本