obsidian-mcp-search 0.1.0

Self-hosted MCP server exposing embedding-powered semantic search over an Obsidian vault

obsidian-mcp-search

Self-hosted MCP server that exposes embedding-powered semantic search + graph context over your Obsidian vault(s). Point it at a folder of .md files and it serves hybrid (BM25 + vector + alias) search to any MCP client — with a web dashboard to manage vaults and the embedding index.

• No external index: walks a plain Obsidian vault directly
• Local embeddings by default (intfloat/multilingual-e5-small, no API key); OpenAI/Azure optional
• Returns the matching passage plus heading breadcrumb, tags, aliases, outbound links and backlinks
• Multiple vaults from one server, each incrementally indexed and watched
• Web admin dashboard at /admin

Install

pip / uvx

pip install obsidian-mcp-search
# Or install with the server extra (includes uvicorn + fastmcp):
pip install "obsidian-mcp-search[server]"
obsidian-mcp-search add-vault main /path/to/your/vault
obsidian-mcp-search serve

One-line installer (registers an auto-start service)

./install.sh --vault /path/to/your/vault
# macOS -> launchd, Linux -> systemd; prints dashboard URL + client config

Docker

echo "VAULT_PATH=/path/to/your/vault" > .env
docker compose up --build -d

Connect an MCP client

Add to your client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian-search": {
      "url": "http://127.0.0.1:8848/mcp"
    }
  }
}

Tools exposed: search(query, k, vault, mode), list_vaults(), read_note(vault, path, section?), reindex(vault).

Dashboard

Open http://127.0.0.1:8848/admin to add/remove vaults, reindex, clear an index, switch the embedding model (re-embeds all vaults), and watch live status.

Remote dashboard note: The /admin dashboard is intended for localhost use (default: no token, works fully in a browser). Browsers cannot attach Authorization: Bearer headers to page navigations or htmx background requests, so if you need to access the dashboard remotely you must front the server with a reverse proxy that handles authentication (e.g. nginx auth_basic or an SSO proxy), or use an SSH tunnel (ssh -L 8848:127.0.0.1:8848 yourhost). The bearer token set via MCP_AUTH_TOKEN still fully protects the /mcp endpoint for all MCP clients that send the Authorization header correctly.

Configuration (env vars)

Var	Default	Meaning
OMCS_HOST	127.0.0.1	bind address (set 0.0.0.0 to expose)
OMCS_PORT	8848	port
MCP_AUTH_TOKEN	(unset)	bearer token; required when bound off-localhost
OMCS_EMBED_BACKEND	local	local (fastembed) or openai
OMCS_EMBED_MODEL	intfloat/multilingual-e5-small	embedding model
OMCS_EMBED_BASE_URL	(unset)	Azure/OpenAI-compatible base URL
OMCS_PREFER_SQLITE_VEC	0	1 to use sqlite-vec when loadable

Indexes live in ~/.cache/obsidian-mcp-search/<vault-hash>/; the vault registry in ~/.config/obsidian-mcp-search/config.toml. Your notes are never written to.

Security

Binds to localhost by default. To expose remotely, set MCP_AUTH_TOKEN and OMCS_HOST=0.0.0.0; the /mcp endpoint then requires Authorization: Bearer <token> from all MCP clients. See the Dashboard section above for notes on remote /admin access.

License

MIT.