Obsidian Semantic Search

---

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)

Search Modes

Installation

Prerequisites

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

**Linux (3 modes):**

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:

| 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

osm status       # Check health
osm rebuild      # Rebuild Docker images after updates
osm remove       # Stop and clean up everything

Architecture

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

---

*Built by [celstnblacc](https://github.com/celstnblacc) — 207 unit tests, Docker + native install, multi-vault support.*