enquire-mcp

The most advanced Obsidian MCP server. Period.

Every modern IR primitive. In one tool. For free.

First and only Obsidian-MCP that ships hybrid retrieval, cross-encoder reranking, HNSW, int8 quantization, late-chunking, HyDE, GraphRAG-light community detection, standalone .base query execution, PDFs + OCR, and stateful remote MCP — together. In one binary. Under MIT. SLSA-3 signed.

What it is

A production-ready MCP server that gives any AI agent — Claude Code, Claude Desktop, Cursor, ChatGPT custom GPT, Codex, mobile MCP clients — structured access to your Obsidian vault. The umbrella obsidian_search tool fuses BM25 + TF-IDF + multilingual ML embeddings via Reciprocal Rank Fusion (Cormack et al, 2009), reranks with a BGE cross-encoder (5 model options), scales to millions of chunks via HNSW with int8 quantization, and returns blended markdown + PDF hits with [page: N] citations.

44 tools · 19 MCP prompts · 664 unit tests · 50+ languages · v3.5 · semver-bound · MIT · SLSA-3.

⚡ Quick start

npm install -g @oomkapwn/enquire-mcp
enquire-mcp serve --vault ~/Documents/Obsidian\ Vault

Drop into any MCP client:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@oomkapwn/enquire-mcp", "serve", "--vault", "/path/to/vault"]
    }
  }
}

📂 Drop-in configs in examples/ — Claude Desktop, Cursor, ChatGPT custom GPT (remote MCP over HTTP), plus a sample query set for the eval harness.

Want full hybrid power? One-command zero-touch onboarding:

enquire-mcp setup --vault <path>     # downloads model, builds FTS5 + embed-db
enquire-mcp serve --vault <path> --persistent-index --enable-reranker --use-hnsw
enquire-mcp doctor --vault <path>    # color-coded ✓/⚠/✗ health check

🏆 Why it's the best

Six features no other Obsidian-MCP has at all (GraphRAG-light, standalone .base execution, HyDE, int8 quantization, late-chunking, built-in eval harness). Plus the entire modern IR stack (BM25 + ML embeddings + cross-encoder reranking + HNSW) that competitors ship at most one or two of. Side-by-side:

| Capability | enquire-mcp | Smart Connections | Other Obsidian-MCPs | |---|:---:|:---:|:---:| | Hybrid retrieval (BM25 + TF-IDF + ML embeddings, RRF-fused) | ✅ | ❌ | ❌ | | Cross-encoder reranking (BGE, +5-10 NDCG@10) | ✅ | ❌ | ❌ | | HNSW vector index (sub-10ms top-K, persisted) | ✅ | ❌ | ❌ | | int8 vector quantization (~4× smaller embed-db) | ✅ | ❌ | ❌ | | Late-chunking context-windowed embeddings | ✅ | ❌ | ❌ | | PDFs blended into hybrid search ([page: N] citations) | ✅ | ❌ | ❌ | | OCR for scanned PDFs (Tesseract.js, multilingual) | ✅ | ❌ | ❌ | | Wikilink graph-boost retrieval signal | ✅ | ❌ | ❌ | | Multilingual semantic search (50+ languages, on-device) | ✅ | 💰 paid | ❌ | | Built-in retrieval-quality eval harness (NDCG, Recall, MRR, A/B matrix) | ✅ | ❌ | ❌ | | Remote MCP over HTTP + bearer auth + stateful sessions | ✅ | ❌ | partial | | Per-signal observability per hit | ✅ | ❌ | ❌ | | MCP-native (Claude · Cursor · ChatGPT · Codex · any client) | ✅ | ❌ Obsidian-only | varies | | Privacy filter verified at every search + write path | ✅ | n/a | ❌ | | 44 production tools (33 always-on read tools + 4 opt-in + 7 gated writes) | ✅ | n/a | varies | | GraphRAG-light (wikilink community detection via Louvain modularity) | ✅ only here | ❌ | ❌ | | Standalone .base query execution (works without Obsidian running) | ✅ only here | ❌ | ❌ delegates to Obsidian | | HyDE retrieval (Gao et al 2023) + sub-question decomposition | ✅ only here | ❌ | ❌ | | 664 unit tests · 8 required + 4 advisory CI gates per PR | ✅ | n/a | rare | | SLSA-3 build provenance | ✅ | n/a | ❌ | | Semver-bound public surface (STABILITY.md) | ✅ | n/a | ❌ | | Standalone (no Obsidian plugin needed) | ✅ | ❌ requires Obsidian | varies | | License | MIT, free | proprietary, paid | varies |

Comparison based on each project's public capabilities as documented at v3.0 release (2026-05-09). Smart Connections is a paid Obsidian plugin (not an MCP server). "Other Obsidian-MCPs" refers to public open-source Obsidian-MCP servers on GitHub at time of writing.

Strategic claim: enquire-mcp is the open-source backend for Karpathy-style LLM Wikis on top of your existing Obsidian vault. Knowledge that compounds, traceable to sources.

🏗️ How retrieval works

graph LR
    Q[Query] --> S[obsidian_search]
    S --> BM25[BM25 / FTS5]
    S --> TFIDF[TF-IDF cosine]
    S --> EMB[ML embeddings<br/>HNSW]
    BM25 --> RRF{RRF fusion<br/>k=60}
    TFIDF --> RRF
    EMB --> RRF
    RRF --> GB[Graph boost<br/>α × in-degree]
    GB --> RR[BGE cross-encoder<br/>reranker]
    RR --> R[Ranked hits<br/>per_signal observability]

obsidian_search auto-detects available signals and gracefully degrades. Wikilink graph-boost reranks top-K via 1-step personalised PageRank. Optional cross-encoder reranking re-scores top-N for +5-10 NDCG@10. Every hit returns per_signal: { bm25, tfidf, embeddings } so you see WHY it ranked.

| Tier | Setup | What you get | |---|---|---| | 1 | serve --vault <path> | TF-IDF cosine (zero setup, instant) | | 2 | + --persistent-index | + BM25 / FTS5 (sub-100ms top-10) | | 3 | + setup (downloads model + builds embed-db) | + multilingual ML embeddings | | 4 | + --enable-reranker | + BGE cross-encoder (+5-10 NDCG@10) | | 5 | + --use-hnsw | + sub-10ms top-K at million-chunk scale | | 6 | + --include-pdfs | + PDFs blended into all of the above | | 7 | serve-http --bearer-token … | + remote MCP (Claude.ai web, ChatGPT, Cursor HTTP, mobile) |

🛠️ All 44 tools

The umbrella obsidian_search plus 43 specialized tools (33 always-on read + 4 opt-in + 7 gated writes). Full reference: docs/api.md.

| Category | Tools | |---|---| | Search & retrieval | obsidian_search (umbrella, RRF-fused) · obsidian_hyde_search (HyDE-augmented, v3.1.0) · obsidian_search_text · obsidian_full_text_search · obsidian_semantic_search · obsidian_embeddings_search · obsidian_find_similar | | Wikilinks & graph | obsidian_resolve_wikilink · obsidian_get_backlinks · obsidian_get_outbound_links · obsidian_get_note_neighbors · obsidian_get_unresolved_wikilinks · obsidian_find_path · obsidian_get_communities (v3.4.0, GraphRAG-light) | | Frontmatter & Dataview | obsidian_frontmatter_get · obsidian_frontmatter_search · obsidian_dataview_query · obsidian_list_tags | | Read & navigate | obsidian_read_note · obsidian_list_notes · obsidian_get_recent_edits · obsidian_open_questions · obsidian_context_pack · obsidian_chat_thread_read · obsidian_open_in_ui · obsidian_stats | | PDFs, Canvas & Bases | obsidian_read_pdf · obsidian_list_pdfs · obsidian_ocr_pdf · obsidian_read_canvas · obsidian_list_canvases · obsidian_list_bases (v3.2.0) · obsidian_read_base (v3.2.0) · obsidian_query_base (v3.2.0) | | Writes (gated by --enable-write) | obsidian_create_note · obsidian_append_to_note · obsidian_rename_note · obsidian_replace_in_notes · obsidian_archive_note · obsidian_frontmatter_set · obsidian_chat_thread_append | | Diagnostic / lint | obsidian_lint_wiki · obsidian_paper_audit · obsidian_validate_note_proposal |

Plus 3 MCP resources (obsidian://vault/info, obsidian://note/{path}, obsidian://chunk/{n}/{path}) and 19 MCP prompts (summarize_recent_edits · review_tag · find_orphans · weekly_review · extract_todos · process_inbox · consolidate_tags · find_duplicates · lint_wiki · monthly_review · search_with_query_expansion · vault_synth · vault_wiki_compile · vault_lint_extended · vault_capture · vault_persona_search · vault_automation_setup · vault_research · vault_synthesis_page) for common vault workflows.

🛡️ Trust

| Surface | Posture | |---|---| | Default | Read-only — --enable-write required for the 7 write tools | | Path safety | Realpath check on every read+write; symlinks-out-of-vault rejected | | Privacy filter | Verified at FTS5 + embed-db + chunk resource paths; fail-closed on empty allow-/deny-lists | | HTTP transport | Bearer auth (constant-time SHA-256 + timingSafeEqual), per-token rate-limit, strict CORS | | Frontmatter | gray-matter (js-yaml safeLoad) — no code execution | | Cache + index files | chmod 0600, parent dir 0700 | | CI | 8 required branch-protection gates (lint · test ×3 [Node 20/22/24] · smoke · audit · coverage · version-consistency) + 4 advisory (test-macos · CodeQL ×2 · Analyze actions). Release workflow re-verifies all 8 required passed on tagged SHA before npm publish. | | Coverage | Lines ≥86% · statements ≥82% · functions ≥75% · branches ≥73% (gated) | | Releases | npm + GitHub release per tag · semver · SLSA-3 build provenance | | Stability | v3.0+ semver-bound — every CLI flag, tool name, MCP resource, prompt, exported symbol is contract |

Full posture: SECURITY.md · Stability surface: STABILITY.md · Vulns: [email protected].

❓ FAQ

Need Obsidian installed? No. Reads .md + .canvas + .pdf directly. Works against any Obsidian-format vault.

Will it write to my vault? Not unless you pass --enable-write. All 7 write tools are gated; destructive ones support dry_run.

Data sent anywhere? Only on enquire-mcp install-model (downloads ONNX weights from HuggingFace, one-time). Serve mode never makes outbound HTTP. Embeddings + reranker run on CPU locally.

Performance? Cold-build FTS5: ~5s/1k notes, ~30s/50k. BM25 query: <100ms always. Embedding build: ~30ms/chunk on M1. HNSW top-10: sub-10ms at any scale. Serve cold-start: ~50ms with HNSW persistence.

Languages? Default paraphrase-multilingual-MiniLM-L12-v2 (50+ languages). Multilingual cross-encoder. Validated end-to-end on Russian + English bilingual vaults. CJK/Thai/Khmer tokenization via Intl.Segmenter.

Run remotely? Yes — serve-http exposes the same server over Streamable HTTP. Front with Tailscale Funnel or Cloudflare Tunnel for HTTPS. Works with claude.ai web, ChatGPT custom GPT, Cursor HTTP mode, mobile MCP clients. See docs/http-transport.md.

🚀 Releases

v3.0.0 — stable channel. The v2.x retrieval roadmap is complete and the public surface is now semver-bound. Highlight reel of the v2.x line that landed in v3.0:

v2.0 hybrid retrieval (BM25+TF-IDF+embeddings via RRF) · v2.6 remote MCP · v2.7-2.8 PDFs blended · v2.9 BGE reranker · v2.10 OCR · v2.11 doctor + setup · v2.12 eval harness · v2.13 HNSW · v2.14 stateful sessions · v2.15 late-chunking · v2.16 HNSW persistence · v2.17 int8 quantization

Channel: npm install @oomkapwn/enquire-mcp → latest stable. Full changelog: CHANGELOG.md.

🤝 Contributing

git clone https://github.com/oomkapwn/enquire-mcp.git
cd enquire-mcp && npm install
npm test       # full suite (664 tests, ~5s)
npm run lint   # zero warnings
npm run build  # tsc → dist/

Issues, PRs, ideas welcome. Branch protection requires PR review on main.

📜 License

MIT. Built by Alex (@OomkaBear). Named after Tim Berners-Lee's 1980 prototype of the WWW — the original hypertext system, before the web. The original spec was: you could ask the system anything. enquire-mcp brings that to your vault.