Obsidian に蓄積した数百、数千のメモを、Claude Code から自然言語で検索できたら便利だと思いませんか？

qmd （Query Markup Documents）は、Shopify CEO Tobi Lütkeが個人開発したローカルRAG検索エンジンです。サンドボックス実行ツールtry の作者でもあります。BM25全文検索、ベクター検索、LLMリランキングの3層構成で、Markdownノート・議事録・ドキュメントを高精度に検索できます。

本記事では、qmdをModel Context Protocol （MCP）サーバーとして設定し、Claude Codeから「Obsidianのメモを検索する」ワークフローを構築する手順を解説します。

qmdとは何か

qmdは、ローカル環境で動作するMarkdown検索エンジンです。以下の3つの検索手法を組み合わせて、高精度な検索結果を返します。

3層ハイブリッド検索アーキテクチャ

この3層構成により、「キーワードは一致しないが意味的に関連する文書」も見つけられます。

完全ローカル実行

qmdはnode-llama-cpp を使用し、以下のGGUFモデルをローカルで実行します：

• embeddinggemma-300M-Q8_0: ベクター埋め込み生成（約300MB）
• qwen3-reranker-0.6b-q8_0: 検索結果のリランキング（約640MB）
• qmd-query-expansion-1.7B-q4_k_m: クエリ拡張（約1.1GB）

すべてのモデルは初回実行時に自動ダウンロードされ、~/.cache/qmd/models/ にキャッシュされます。

qmdのインストール

前提条件

• Bun: 1.0.0以上（公式サイト からインストール）
• macOS: Homebrew版SQLite（拡張機能サポートのため）

macOSの場合、Homebrew版SQLiteをインストールします：

1

brew install sqlite

qmdのインストール

1
2
3
4
5

# グローバルインストール
bun install -g https://github.com/tobi/qmd

# インストール確認
qmd --version

~/.bun/bin がPATHに含まれていることを確認してください。

Obsidian Vaultのインデックス作成

コレクションの追加

qmdでは、検索対象のディレクトリを「コレクション」として登録します。Obsidian Vaultをコレクションとして追加しましょう。

1
2
3
4
5

# Obsidian Vaultをコレクションとして追加
qmd collection add ~/Documents/ObsidianVault --name obsidian

# コレクション一覧を確認
qmd collection list

複数のVaultがある場合は、それぞれ別のコレクションとして追加できます：

1
2

qmd collection add ~/Documents/WorkNotes --name work
qmd collection add ~/Documents/PersonalNotes --name personal

コンテキストの追加

コンテキストは、コレクションやパスに説明を付与する機能です。検索時にこの情報がLLMに渡され、検索精度が向上します。

1
2
3
4
5
6
7
8
9

# コレクション全体にコンテキストを追加
qmd context add qmd://obsidian "Obsidianで管理している個人メモとアイデア"

# 特定のディレクトリにコンテキストを追加
qmd context add qmd://obsidian/projects "プロジェクト関連のメモ"
qmd context add qmd://obsidian/daily "デイリーノート"

# コンテキスト一覧を確認
qmd context list

ベクター埋め込みの生成

インデックス作成後、ベクター検索用の埋め込みを生成します。この処理は初回のみ必要で、ドキュメント数に応じて数分〜数十分かかります。

1
2
3
4
5

# 埋め込み生成（800トークン/チャンク、15%オーバーラップ）
qmd embed

# 強制再生成（すべてのドキュメントを再処理）
qmd embed -f

埋め込み生成中は、進行状況がターミナルに表示されます。

MCPサーバーとしての設定

qmdは、MCPサーバーとして動作し、Claude CodeやClaude Desktopから直接呼び出せます。

Claude Codeでの設定

Claude Codeでは、プラグインとして簡単にインストールできます：

1
2
3

# qmdプラグインをインストール
claude marketplace add tobi/qmd
claude plugin add qmd@qmd

または、MCPサーバーとして手動設定する場合は、~/.claude/settings.json に以下を追加します：

1
2
3
4
5
6
7
8

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Claude Desktopでの設定

Claude Desktopの場合、設定ファイルは ~/Library/Application Support/Claude/claude_desktop_config.json です：

1
2
3
4
5
6
7
8

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

OpenCode / Crushでの設定

OpenCode （現在はCrush に移行）の場合、.opencode.json または ~/.config/opencode/.opencode.json に以下を追加します：

1
2
3
4
5
6
7
8
9

{
  "mcpServers": {
    "qmd": {
      "type": "stdio",
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

OpenAI Codex CLIでの設定

Codex CLI もMCPサーバーに対応しています。詳細な設定方法は公式ドキュメント を参照してください。

設定後、各ツールを再起動すると、qmdのMCPツールが利用可能になります。

MCPツールの使い方

qmdは、以下の6つのMCPツールを提供します：

基本的な使い方

Claude Codeで以下のように指示すると、qmdが自動的に呼び出されます：

「Obsidianのメモから、プロジェクトAに関連する内容を探して」

Claude Codeは内部で qmd_query ツールを呼び出し、検索結果を返します。

コレクションを指定した検索

特定のコレクションに絞って検索する場合：

「workコレクションから、API設計に関するメモを探して」

Claude Codeは -c work オプション付きで検索を実行します。

ドキュメントの取得

検索結果から特定のドキュメントを全文取得する場合：

「さっきの検索結果の1番目のドキュメントを全文表示して」

Claude Codeは qmd_get ツールを使用し、docid（例: #a1b2c3）でドキュメントを取得します。

検索精度を高めるコツ

クエリ拡張の活用

qmdは、元のクエリに加えて、LLMが生成した2つの拡張クエリを使用します。元のクエリには2倍の重みが付けられるため、キーワードが明確な場合は正確に検索できます。

# 良い例（具体的なキーワード）
「Docker Composeの設定方法」

# 良い例（自然な質問）
「エラーハンドリングのベストプラクティスは？」

コンテキストの活用

コンテキストを適切に設定すると、検索精度が大幅に向上します：

1
2
3

# プロジェクト別にコンテキストを追加
qmd context add qmd://obsidian/projects/projectA "プロジェクトA: 決済システムの開発"
qmd context add qmd://obsidian/projects/projectB "プロジェクトB: 管理画面のリニューアル"

これにより、「決済システムのエラーハンドリング」のような検索で、プロジェクトAのメモが優先的に返されます。

定期的なインデックス更新

Obsidianでメモを追加・更新した後は、インデックスを更新します：

1
2
3
4
5

# インデックス更新
qmd update

# 埋め込みの再生成（新規ドキュメントのみ）
qmd embed

実践例: Claude Codeとの連携ワークフロー

例1: 過去のメモから関連情報を探す

ユーザー: 「去年のプロジェクトで使ったAPI認証の方法を教えて」

Claude Code: 
1. qmd_query を実行（「API認証 プロジェクト」で検索）
2. 検索結果の上位3件を要約
3. 必要に応じて qmd_get で全文取得
4. 認証方法を整理して回答

例2: 複数のメモを横断して情報を統合

ユーザー: 「エラーハンドリングに関するメモを全部集めて、ベストプラクティスをまとめて」

Claude Code:
1. qmd_query で「エラーハンドリング」を検索
2. qmd_multi_get で関連ドキュメントを一括取得
3. 内容を分析し、共通パターンを抽出
4. ベストプラクティスとしてまとめて提示

例3: 特定の期間のメモを検索

ユーザー: 「2025年1月のデイリーノートから、重要なタスクを抽出して」

Claude Code:
1. qmd_multi_get で「daily/2025-01-*.md」を取得
2. 各ノートからタスクを抽出
3. 優先度順にリスト化

qmdの検索アルゴリズム詳細

Reciprocal Rank Fusion（RRF）

qmdは、複数の検索結果を統合するために、RRFアルゴリズムを使用します：

score = Σ(1 / (k + rank + 1))

ここで、k=60 が定数として使用されます。

Top-Rank Bonus

検索結果の1位には +0.05、2〜3位には +0.02 のボーナススコアが付与されます。これにより、完全一致に近い結果が優先されます。

Position-Aware Blending

リランキング後、RRFスコアとリランカースコアを以下の比率でブレンドします：

この設計により、完全一致を保ちつつ、意味的に関連する文書も適切に評価されます。

トラブルシューティング

検索結果が返らない

原因: 埋め込みが生成されていない

1
2
3
4
5

# 埋め込み生成状態を確認
qmd status

# 埋め込みを生成
qmd embed

MCPツールが認識されない

原因: Claude Code/Desktopが設定を読み込んでいない

1. Claude Code/Desktopを再起動
2. qmd mcp コマンドが単独で動作するか確認：

1
2

# MCPサーバーをテスト実行
qmd mcp

3. 設定ファイルのパスが正しいか確認

検索が遅い

原因: 大量のドキュメントがある場合、初回検索は遅くなります

• LLMキャッシュが有効化されるまで待つ（2回目以降は高速化）
• コレクションを分割して、検索対象を絞る

qmdとLEANNの比較

同じローカルRAGツールとして、LEANN との違いを整理します：

qmdは「検索精度と速度を優先」、LEANNは「ストレージ効率を優先」という設計思想の違いがあります。

まとめ

qmdを使うことで、Obsidianに蓄積したメモを、Claude Codeから自然言語で検索できるようになります。

qmdの強み:

• BM25+ベクター+リランキングの3層構成で高精度
• 完全ローカル実行でプライバシー保護
• MCPサーバーとして、Claude Code/Desktopとシームレスに統合
• Shopify CEOが実際に使っている実用的な設計

おすすめの使い方:

• 過去のメモから関連情報を探す
• 複数のメモを横断して情報を統合
• デイリーノートからタスクを抽出

Obsidianユーザーで、Claude Codeを使っている方は、ぜひ試してみてください。

参考リンク

• qmd - GitHub
• Model Context Protocol
• Claude Code
• Crush（旧OpenCode）
• OpenAI Codex CLI
• Obsidian
• node-llama-cpp
• sqlite-vec
• LEANN: 97%ストレージ削減のプライベートRAGシステム徹底解説