Skill: celstnblacc/obsidian-semantic-search (version 1.0.1)

--- name: "Obsidian Semantic Search" description: "Semantic search across your Obsidian vaults using local embeddings (Ollama + pgvector). 10 MCP tools: hybrid/semantic/keyword search, file CRUD, batch reads, live re-indexing, and a monitoring dashboard. Fully local — no API keys, no cloud, zero cost." version: "1.0.0" emoji: "🧠" homepage: "https://github.com/celstnblacc/obsidian-semantic-mcp" user-invocable: true disable-model-invocation: false requires: bins: ["docker", "uv"] anyBins: ["python3", "python"] env: ["OBSIDIAN_VAULT"] --- # Obsidian Semantic Search Search your Obsidian vault by **meaning**, not just keywords. This skill installs and configures [obsidian-semantic-mcp](https://github.com/celstnblacc/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 | |------|-------------| | `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 | ### 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", [REDACTED_SECRET], "python3", "src/server.py"] } } } ``` Restart Claude Desktop after adding. ## Configuration 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 | ## 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 | 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](https://github.com/celstnblacc) — 207 unit tests, Docker + native install, multi-vault support.*


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)