Obsidian Hybrid Search — Claude Code MCP server for vault search
An MCP server that lets your agent search an Obsidian vault by meaning, title and links, read notes, and pull cited context from your own files.
claude mcp add --env OBSIDIAN_VAULT_PATH=<OBSIDIAN_VAULT_PATH> --env OBSIDIAN_PREFIX=<OBSIDIAN_PREFIX> --env OBSIDIAN_IGNORE_PATTERNS=<OBSIDIAN_IGNORE_PATTERNS> --env OBSIDIAN_RESPECT_GITIGNORE=<OBSIDIAN_RESPECT_GITIGNORE> --env OBSIDIAN_INCLUDE_PATTERNS=<OBSIDIAN_INCLUDE_PATTERNS> --transport stdio obsidian-hybrid-search -- npx -y obsidian-hybrid-searchWhat Obsidian Hybrid Search does
Obsidian Hybrid Search fuses several retrieval methods into one engine: BM25 full text, fuzzy title and alias matching, semantic embeddings, and graph traversal. Results merge through RRF, so a note surfaces even when you don't recall the exact wording. Text queries support four modes: hybrid, semantic, fulltext, and title.
Agents can read notes by vault-relative path, look up similar notes, and walk links with a direction filter (outgoing, backlinks, both). Indexing is incremental, so only changed files get re-indexed. Local embeddings run offline through @huggingface/transformers, with Xenova/multilingual-e5-small as the default model. An OpenAI-compatible API such as OpenRouter or Ollama is supported too.
You need a vault path in OBSIDIAN_VAULT_PATH to start. Remote embeddings require OPENAI_API_KEY; without it the server falls back to the local model. The optional --rerank flag pulls gte-multilingual-reranker-base (ONNX int8, about 341 MB) and slows responses noticeably — turn it on when precision on conceptual queries matters more than speed.
What it helps with
- find a note by meaning when you forget the wording
- feed cited context from an Obsidian vault into an agent answer
- hop from one note to its linked neighbours
- narrow results by tag or subfolder
- read several notes by path in one call
Example prompts for the agent
- Find notes in my vault about incremental indexing and quote them
- Show notes linked to
notes/dev/architecture.mdtwo levels deep - Find notes similar to
notes/ideas/retrieval.md
How to install Obsidian Hybrid Search
Platform CLI
claude mcp add --env OBSIDIAN_VAULT_PATH=<OBSIDIAN_VAULT_PATH> --env OBSIDIAN_PREFIX=<OBSIDIAN_PREFIX> --env OBSIDIAN_IGNORE_PATTERNS=<OBSIDIAN_IGNORE_PATTERNS> --env OBSIDIAN_RESPECT_GITIGNORE=<OBSIDIAN_RESPECT_GITIGNORE> --env OBSIDIAN_INCLUDE_PATTERNS=<OBSIDIAN_INCLUDE_PATTERNS> --transport stdio obsidian-hybrid-search -- npx -y obsidian-hybrid-searchReplace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
codex mcp add obsidian-hybrid-search --env OBSIDIAN_VAULT_PATH=<OBSIDIAN_VAULT_PATH> --env OBSIDIAN_PREFIX=<OBSIDIAN_PREFIX> --env OBSIDIAN_IGNORE_PATTERNS=<OBSIDIAN_IGNORE_PATTERNS> --env OBSIDIAN_RESPECT_GITIGNORE=<OBSIDIAN_RESPECT_GITIGNORE> --env OBSIDIAN_INCLUDE_PATTERNS=<OBSIDIAN_INCLUDE_PATTERNS> -- npx -y obsidian-hybrid-searchReplace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"mcpServers": {
"obsidian-hybrid-search": {
"command": "npx",
"args": [
"-y",
"obsidian-hybrid-search"
],
"env": {
"OBSIDIAN_VAULT_PATH": "<OBSIDIAN_VAULT_PATH>",
"OBSIDIAN_PREFIX": "<OBSIDIAN_PREFIX>",
"OBSIDIAN_IGNORE_PATTERNS": "<OBSIDIAN_IGNORE_PATTERNS>",
"OBSIDIAN_RESPECT_GITIGNORE": "<OBSIDIAN_RESPECT_GITIGNORE>",
"OBSIDIAN_INCLUDE_PATTERNS": "<OBSIDIAN_INCLUDE_PATTERNS>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"servers": {
"obsidian-hybrid-search": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"obsidian-hybrid-search"
],
"env": {
"OBSIDIAN_VAULT_PATH": "<OBSIDIAN_VAULT_PATH>",
"OBSIDIAN_PREFIX": "<OBSIDIAN_PREFIX>",
"OBSIDIAN_IGNORE_PATTERNS": "<OBSIDIAN_IGNORE_PATTERNS>",
"OBSIDIAN_RESPECT_GITIGNORE": "<OBSIDIAN_RESPECT_GITIGNORE>",
"OBSIDIAN_INCLUDE_PATTERNS": "<OBSIDIAN_INCLUDE_PATTERNS>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
gemini mcp add -e OBSIDIAN_VAULT_PATH=<OBSIDIAN_VAULT_PATH> -e OBSIDIAN_PREFIX=<OBSIDIAN_PREFIX> -e OBSIDIAN_IGNORE_PATTERNS=<OBSIDIAN_IGNORE_PATTERNS> -e OBSIDIAN_RESPECT_GITIGNORE=<OBSIDIAN_RESPECT_GITIGNORE> -e OBSIDIAN_INCLUDE_PATTERNS=<OBSIDIAN_INCLUDE_PATTERNS> obsidian-hybrid-search npx -y obsidian-hybrid-searchReplace <…> with your own values. 5 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Obsidian Hybrid Search
How do I install Obsidian Hybrid Search in Claude Code?
Run `claude mcp add obsidian-hybrid-search -e OBSIDIAN_VAULT_PATH=<OBSIDIAN_VAULT_PATH> -e OPENAI_API_KEY=<OPENAI_API_KEY> -- npx -y obsidian-hybrid-search`. Replace the vault path and API key with your own.
What does Obsidian Hybrid Search do?
It gives an agent search over an Obsidian vault: full text, semantics, titles and aliases, plus note links. It also reads notes and finds similar ones.
Do I need an API key for it to work?
No. Local embeddings run offline through @huggingface/transformers. OPENAI_API_KEY is only needed for an OpenAI-compatible API such as OpenRouter or Ollama.
