Obsidian Semantic MCP

OSM adds semantic, keyword, and hybrid search for Obsidian notes to local MCP clients. It reads your Markdown vaults, uses local Ollama for embeddings, and stores the index in either Qdrant or PostgreSQL + pgvector. Your notes remain in Obsidian. The command is osm; the default embedding model is qwen3-embedding:0.6b.

Install and configure

On macOS, install OSM from the Homebrew tap. Homebrew installs the required Python and build tools:

brew install joynik/tap/osm

Install only the services you do not already have:

brew install ollama
brew services start ollama
ollama pull qwen3-embedding:0.6b

Choose one database:

For PostgreSQL, use your installed PostgreSQL major version if it differs from 18:

createdb obsidian_brain
psql -d obsidian_brain -c "CREATE EXTENSION IF NOT EXISTS vector;"

A local database can use postgresql://localhost/obsidian_brain when your PostgreSQL account permits it. Otherwise, enter a URL with your database user and password during osm init. Do not recreate an existing database. Check running Homebrew services with brew services list.

After Ollama and the database are ready, configure OSM:

osm init
osm status

osm init asks for vault paths, database, Ollama URL, model, and other settings. You can add more vaults by running it again. It saves installed settings in ~/.config/osm/runtime.json. Existing settings are copied there automatically on first use. To update OSM after a new tap release, run brew update && brew upgrade joynik/tap/osm.

For development from this checkout, install uv, run uv sync --python 3.14, copy .env.example to .env, fill in your paths and URLs, then use uv run osm .... Saved osm init settings take precedence over the checkout .env.

The wizard asks separately before connecting each MCP client and before granting that client write access. Both answers default to No. osm init can exclude an archive folder from indexing; its default name is Archive, and you can enter another folder name.

Related MCP server: freshvault

Run and check

An MCP client starts osm run when it connects. For a manual launch, keep osm run running in its terminal. Ollama and the chosen database must be available whenever OSM indexes or searches; brew services can start them after login. The dashboard runs only when requested.

osm                 # Choose a command with the arrow keys
osm status          # Check Ollama, database, and vaults
osm vaults          # Show configured vaults
osm logs --follow   # Watch server activity
osm dashboard       # Start or restart the optional local dashboard
osm dashboard stop
osm stop            # Stop local OSM server processes

The dashboard offers English, Russian, Ukrainian, French, Spanish, German, Portuguese, Simplified Chinese, and Japanese. It follows the browser language by default; a manual choice in the top bar is remembered.

If Ollama is unavailable, a running OSM server keeps retrying; on macOS it notifies you after two minutes. osm stop does not stop Ollama or the database. A connected MCP client can start OSM again.

Connect clients manually

You can connect clients during osm init or use the entries below. Restart the client after connecting. OSM_ALLOW_WRITE=0 keeps note-writing tools disabled for that client; change it to 1 only when you want that client to edit notes.

For OpenCode, add this entry inside mcp in ~/.config/opencode/opencode.json, keeping your other entries:

{
  "obsidian-semantic": {
    "type": "local",
    "command": ["osm", "run"],
    "enabled": true,
    "environment": {"OSM_ALLOW_WRITE": "0"}
  }
}

For Claude Desktop on macOS, add an obsidian-semantic entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json with "command": "osm", "args": ["run"], and "env": {"OSM_ALLOW_WRITE": "0"}. Run osm disconnect to remove OSM from supported clients; it does not remove notes, settings, or indexed data.

Search and maintenance

OSM updates the index after note changes and searches long notes in passages. Semantic search uses Ollama; keyword search uses the database index. PostgreSQL text search defaults to Russian; choose English or simple during osm init. Qdrant uses Russian BM25 for keyword search.

To change the embedding model, use migration rather than editing EMBEDDING_MODEL on an existing index:

ollama pull MODEL
osm migrate --embedding-model MODEL --dry-run
osm migrate --embedding-model MODEL

Migration builds new vectors before switching the active index. The dashboard's Safe Rebuild similarly keeps the previous index until a new one is ready. If you change the excluded archive folder after its notes were indexed, use Safe Rebuild to remove those notes from active search. Neither operation deletes Obsidian files.

Other commands: osm open --vault PATH NOTE.md opens a note in Obsidian; osm version, osm -v, and osm -V check the installed version; osm update shows the Homebrew update command; osm help lists all commands.

Tests

Run the full suite from the project directory with PostgreSQL, Qdrant, and Ollama running. osm_codex_test must be a separate test database with the vector extension; the PostgreSQL tests change its tables. The Qdrant test creates and removes its own collection.

PYTEST_DATABASE_URL=postgresql://localhost/osm_test \
PYTEST_QDRANT_URL=http://127.0.0.1:6333 \
PYTEST_OLLAMA_URL=http://127.0.0.1:11434 \
uv run pytest -q