# Obsidian Hybrid 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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 113
- Author: flowing-abyss
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/flowing-abyss/obsidian-hybrid-search
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/obsidian-hybrid-search

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `OBSIDIAN_VAULT_PATH`, `OBSIDIAN_PREFIX`, `OBSIDIAN_IGNORE_PATTERNS`, `OBSIDIAN_RESPECT_GITIGNORE`, `OBSIDIAN_INCLUDE_PATTERNS`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_EMBEDDING_MODEL`, `LOCAL_EMBEDDING_MODEL`, `RERANKER_MODEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: Obsidian

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-search
```
Replace <…> with your own values. 5 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
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-search
```
Replace <…> with your own values. 5 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-search
```
Replace <…> with your own values. 5 more environment variables are in the server README

## When to use it
- 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
- Find notes in my vault about incremental indexing and quote them
- Show notes linked to `notes/dev/architecture.md` two levels deep
- Find notes similar to `notes/ideas/retrieval.md`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md