Obsidian Semantic Search

Semantic search across your Obsidian vaults using local embeddings (Ollama + pgvector). 10 MCP tools: hybrid/semantic/keyword search, file CRUD, batch reads,...

Security Scan

The skill's purpose (local semantic search of an Obsidian vault) is plausible, but the runtime instructions and declared requirements don't fully match and include potentially risky steps (remote install scripts, undocumented env vars, and modifying other app config).

Purpose & Capability

The stated goal—local semantic search of an Obsidian vault using Ollama + pgvector—fits the required use of Docker, Python, and a vault path. However the registry metadata and SKILL.md disagree: SKILL.md expects additional services (Postgres, Ollama, a dashboard) and tools (osm CLI, uv installer) that are not fully reflected in the declared requirements. Requiring 'uv' as a binary is unusual but explained by the SKILL.md installer. Overall capability is coherent but the declared requirements are incomplete.

Instruction Scope

The SKILL.md tells users to run remote install commands (curl|bash), clone a GitHub repo, bootstrap services in Docker, and it instructs adding entries to another application's config file (Claude Desktop JSON in user home). It also references environment variables (POSTGRES_PASSWORD, EMBEDDING_MODEL, OBSIDIAN_VAULTS, DASHBOARD_PORT) that are not listed in the registry metadata. The instructions will read and index user files (expected) but also write configuration into other app paths (modifying Claude Desktop config), which is outside a simple search tool's internal state and increases risk.

Install Mechanism

There is no formal install spec in the registry; the SKILL.md instructs executing remote installers: an install.sh from raw.githubusercontent.com and downloading an installer from astral.sh (uv). Running curl ... | sh is a high-risk pattern because it executes code fetched at runtime. The GitHub raw URL is a well-known host (lower risk than an unknown host) but the astral.sh host is a separate domain. The process will pull and run Docker containers and create persistent services.

Credentials

Declared required env in registry is only OBSIDIAN_VAULT, but SKILL.md requires/mentions several additional env vars (POSTGRES_PASSWORD is marked 'Yes (Docker)', OBSIDIAN_VAULTS, EMBEDDING_MODEL, RERANK_MODEL, DASHBOARD_PORT). The skill also references file-system paths and suggests editing Claude Desktop's config file — these are broader privileges than the simple registry declaration implies. Asking for a database password and the ability to run Docker is proportionate to running a local DB, but the mismatch between declared and used envs is a red flag.

Persistence & Privilege

The skill does not set always:true and defaults to allowing model invocation, which is normal. However the installation creates persistent services (Docker containers, PostgreSQL, watcher) and instructs edits to another application's configuration (Claude Desktop). Persisting services and modifying other app configs combined with the remote-install pattern increases the blast radius if something goes wrong.

What to consider before installing

This skill appears to implement what it claims (local semantic search) but has several mismatches and risky steps you should review before running: 1) SKILL.md asks you to run remote install scripts (curl | sh) — inspect those scripts on GitHub/astral.sh before executing or prefer cloning and running locally. 2) The registry only declared OBSIDIAN_VAULT, but the installer requires additional env vars (POSTGRES_PASSWORD, optional EMBEDDING_MODEL, OBSIDIAN_VAULTS). Provide only a database password you control; do not reuse other secret tokens. 3) The installer will run Docker containers and persist services that read your vault files — consider running initially in a disposable VM or containerized environment. 4) The instructions suggest writing into Claude Desktop's config files in your home directory; back up that config before modifying and only apply the suggested changes if you trust the repo. 5) If you want lower risk, manually git clone the repository, inspect install.sh and any Dockerfiles, and run the setup steps yourself rather than using piped installers. If you are not comfortable auditing the install scripts or exposing a local DB/service, treat this skill as higher-risk.

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

• 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

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

• 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.