Obsidian Semantic Search

Obsidian Semantic Search MCP

書き込みアクセスなしで適切な Obsidian ノートを見つける必要があるエージェント向けの、読み取り専用のセマンティック検索です。

한국어 · クイックスタート · 開発の背景 · 仕組み

---

エージェントが適切なノートを見つけられなければ、Obsidian の保管庫は役に立ちません。

キーワード検索では文脈を見落とします。書き込み機能を備えた Obsidian MCP サーバーは、検索エージェントに必要な範囲を超える機能を公開します。Obsidian プラグインは Obsidian 内では優れていますが、Codex、Claude Desktop、Cursor、その他の MCP クライアントにとって常に適切な境界とは限りません。

このプロジェクトは、機能を絞ったバージョンです。

local Obsidian vault -> read-only scanner -> local SQLite index -> MCP search/read tools

ノートへの書き込みはありません。デフォルトではクラウド埋め込みを使用しません。Obsidian プラグインのランタイムはありません。同期サービスもありません。

ステータス：0.3.1 のアーリープレビューです。サーバーは現在使用できますが、ランキングの挙動とツールのスキーマは 1.0 までに変更される可能性があります。

できること

ニーズ	このサーバーの機能
エージェントが読むべきノートを見つける	Markdown ノートを対象にした、セマンティック検索とキーワード検索のハイブリッド検索
保管庫の安全性を保つ	検索／読み取り／インデックス作成／ステータス確認のみを公開し、書き込み、パッチ適用、移動、名前変更、削除のツールはありません
ローカルファーストを維持する	Ollama の埋め込みを使用し、インデックスをローカルマシンに保存します
エージェントに適した結果を提供する	見出し、抜粋、行範囲を含むファイル単位の検索結果を返します
プラグインの状態に依存しない	ファイルシステムから保管庫を直接読み取るため、Obsidian を起動しておく必要はありません

結果の例：

{
  "path": "02_Projects/RealtimeAPI/05_Interview_QA.md",
  "title": "Interview Q&A",
  "score": 0.7431,
  "matched_sections": [
    {
      "heading": "Level 4 > Redis Lua atomicity",
      "lines": [266, 305],
      "reason": "semantic=1, keyword=0.5565, metadata=0.6"
    }
  ]
}

クイックスタート

必要なもの：

• Node.js >= 24
• Ollama
• Obsidian の保管庫
• Codex、Claude Desktop、Cursor、その他の stdio MCP クライアントなどの MCP クライアント

埋め込みモデルをインストールします：

ollama pull bge-m3
curl http://localhost:11434/api/tags

セットアップ手順を表示します：

npx -y --package @dalecb/obsidian-semantic-mcp obsidian-semantic-mcp-setup

Codex のセットアップ

これを ~/.codex/config.toml に追加します：

[mcp_servers.obsidian_semantic]
command = "npx"
args = ["-y", "@dalecb/obsidian-semantic-mcp"]

[mcp_servers.obsidian_semantic.env]
OBSIDIAN_VAULT_ROOT = "/path/to/your/Obsidian Vault"
OBSIDIAN_SEMANTIC_MCP_HOME = "/Users/you/.obsidian-semantic-mcp"
OLLAMA_BASE_URL = "http://localhost:11434"
OBSIDIAN_EMBED_MODEL = "bge-m3"
OBSIDIAN_SEMANTIC_AUTO_INDEX = "true"

Codex を再起動してから、次を実行します：

obsidian_semantic.index_status
obsidian_semantic.search_notes { "query": "Redis Lua atomicity", "limit": 5 }

Claude Code のセットアップ

個人用の保管庫パスがプロジェクトの .mcp.json ファイルに含まれないよう、ユーザースコープでサーバーを追加します：

claude mcp add obsidian_semantic --scope user \
  --env OBSIDIAN_VAULT_ROOT="/path/to/your/Obsidian Vault" \
  --env OBSIDIAN_SEMANTIC_MCP_HOME="/Users/you/.obsidian-semantic-mcp" \
  --env OLLAMA_BASE_URL="http://localhost:11434" \
  --env OBSIDIAN_EMBED_MODEL="bge-m3" \
  --env OBSIDIAN_SEMANTIC_AUTO_INDEX="true" \
  -- npx -y @dalecb/obsidian-semantic-mcp

claude mcp get obsidian_semantic

Claude Code の新しいセッションを開始し、/mcp を実行してサーバーが接続されていることを確認します。ネイティブ Windows では、環境変数のフラグの後に -- cmd /c npx -y @dalecb/obsidian-semantic-mcp を指定します。

スコープとコマンドの詳細については、Anthropic の Claude Code MCP ドキュメントを参照してください。

Claude Desktop／JSON MCP クライアントのセットアップ

Claude Desktop で Settings → Developer → Edit Config を開きます。macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json が開きます。次のサーバー設定を mcpServers に統合します：

{
  "mcpServers": {
    "obsidian_semantic": {
      "command": "npx",
      "args": ["-y", "@dalecb/obsidian-semantic-mcp"],
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/your/Obsidian Vault",
        "OBSIDIAN_SEMANTIC_MCP_HOME": "/Users/you/.obsidian-semantic-mcp",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OBSIDIAN_EMBED_MODEL": "bge-m3",
        "OBSIDIAN_SEMANTIC_AUTO_INDEX": "true"
      }
    }
  }
}

Claude Desktop を完全に終了して再起動します。Cursor やその他の JSON 形式の stdio MCP クライアントでも、同じ mcpServers エントリーを使用できます。Windows で npx が見つからない場合は、"command": "cmd" を使用し、args の先頭に "/c", "npx" を追加します。

Claude Desktop の設定とログについては、公式のローカル MCP サーバーガイドを参照してください。

このプロジェクトの目的

これは、最も強力な Obsidian 自動化サーバーを目指すものではありません。エージェントに安心して任せられる、最も安全な検索ツールを目指しています。

通常比較対象となる 2 つのツール、つまりすべての権限を持つ Obsidian MCP サーバー（Local REST API ベース）と、より幅広い知識のコンパイルプラットフォームである GBrain と比べると、次のようになります。

	このプロジェクト	すべての権限を持つ Obsidian MCP	GBrain
アクセスモデル	読み取り専用：検索／読み取り／インデックス作成	読み取り＋書き込み＋編集＋削除	読み取り＋書き込み。ノートを独自のモデルにコンパイル
Vault への変更	なし	あり	あり — コンテンツを再構成
Obsidian の起動	不要 — ファイルを直接読み取り	必要 — REST API プラグインが必要	不要
必要なローカル実行環境	Node.js + Ollama	Obsidian + プラグイン	スタンドアロンプラットフォーム
埋め込みとデータ	デフォルトではローカルの Ollama。リモート URL は設定可能	ローカル API。埋め込みは構成によって異なる	組み込みパイプライン。同期は任意
ストレージ	削除して再構築できる単一の SQLite ファイル	プラグインが管理	独自のストア／移行
最適な用途	エージェント向けの小規模な読み取り専用検索境界	Vault 全体の自動化と編集	複数のソースにまたがるコンパイル済みナレッジベースの構築

意図的にトレードオフを設けています。書き込み、編集、Obsidian 内での実行を手放す代わりに、構成要素が減り、影響範囲も小さくなります。

エージェントに次のような質問に答えさせたい場合に使用してください。

• 「このプロジェクトの決定について説明しているノートはどれですか？」
• 「冪等性ペイロードの不一致について書いたファイルを見つけてください。」
• 「この面接のトピックに関連するキャリアのノートを表示してください。」
• 「Vault を検索してください。ただし、変更は加えないでください。」

Obsidian の UI プラグイン、自動ノート生成、または書き込み可能な Vault 自動化が必要な場合は使用しないでください。

ツール

index_status

インデックスのメタデータと安全設定を返します。

index_vault

外部の SQLite インデックスを作成または更新します。

{ "mode": "incremental" }

特定のファイル：

{
  "mode": "incremental",
  "paths": ["02_Projects/My Note.md"]
}

search_notes

意味検索とキーワード検索を組み合わせたランキングでノートを検索します。

{
  "query": "live coding notes",
  "limit": 8,
  "mode": "hybrid"
}

モード：

• hybrid：意味ベクトル＋SQLite FTS5＋メタデータによるブースト
• semantic：ベクトル優先の検索
• keyword：クエリを埋め込みに変換せず、FTS5 でキーワード検索

read_note

Vault からの相対パスで指定したノート、または行範囲を読み取ります。

{
  "path": "02_Projects/My Note.md",
  "start_line": 10,
  "end_line": 40
}

仕組み

index_vault
  -> scan Markdown files under OBSIDIAN_VAULT_ROOT
  -> block denied paths and symlink escapes
  -> split notes by Markdown headings
  -> create one summary chunk per file
  -> embed chunks with Ollama bge-m3
  -> store notes, chunks, FTS rows, and vectors in SQLite

search_notes
  -> incrementally index on first search or first search after a Markdown change
  -> embed the query with Ollama
  -> score vector similarity
  -> score SQLite FTS5 keyword matches
  -> apply title/path/heading metadata boosts
  -> regroup chunk matches into file-level results

デフォルトのストレージ：

~/.obsidian-semantic-mcp/
  data/semantic.sqlite

Vault が引き続き信頼できる唯一の情報源です。SQLite データベースは派生インデックスであり、削除して再構築できます。

安全性モデル

サーバーは Vault を読み取りますが、書き込みは行いません。エージェントが参照できる範囲は、3 つの層で決まります。

1. 常に拒否（システム／ツール関連）。 常にインデックス対象外で、例外設定もできません。

• .obsidian/、.smart-env/、.claude/、.codex-*/
• すべての隠しフォルダー（名前が . で始まるもの）
• node_modules、cache、logs

2. 機密情報 — デフォルトでは拒否、解除可能。 サーバーを OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE=true で起動しない限り、ツール呼び出しで include_sensitive: true を指定してもブロックされたままです。デフォルトは 08_PersonalInfo/ です。OBSIDIAN_SEMANTIC_SENSITIVE_PATHS（カンマまたは改行で区切ったフォルダー）でリストを上書きできます。

OBSIDIAN_SEMANTIC_SENSITIVE_PATHS = "08_PersonalInfo, 09_Finance"

3. 独自の除外設定 — 常に拒否。 インデックス作成、検索、読み取りを一切行いたくないフォルダーです。解除フラグはありません。

OBSIDIAN_SEMANTIC_EXCLUDE = "03_Journal, Private, Clients/Acme"

どちらを選びますか？

• 「ここは一切インデックス化しない」 → OBSIDIAN_SEMANTIC_EXCLUDE
• 「ロックしておき、必要なときにフラグで解除できるようにする」 → OBSIDIAN_SEMANTIC_SENSITIVE_PATHS + OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE

追加の保護機能：

• すべてのパスは realpath で解決されます。
• パストラバーサルと URL エンコードされたパストラバーサルはブロックされます。
• Vault のルート外を指すシンボリックリンク、および Vault 内の拒否対象パスを指すシンボリックリンクはブロックされます。

search_notes と read_note は、呼び出しのたびに現在の除外設定を適用します。自動インデックス作成が有効な場合、次回の検索時に、除外された古い行もインデックスから削除されます。有効なリストは index_status で確認してください。

ローカルインデックスにはスニペットと埋め込みベクトルが保存されます。Vault の派生コピーとして取り扱ってください。PRIVACY.md を参照してください。

インデックス作成戦略

デフォルトではタイマーではなく、アクションを契機に実行されます。

1. サーバー起動後、最初の search_notes。
2. Markdown の作成、更新、削除、名前変更イベント後、最初の search_notes。
3. 埋め込みモデルまたはインデックス形式の変更後、最初の search_notes。これによりフル再構築が実行されます。
4. 明示的な index_vault の呼び出し。

ファイルシステムのウォッチャーは、インデックスに変更が必要であることを記録するだけです。インデックス作成は次の検索の直前に一度だけ実行され、並行する検索ではその処理が共有されます。再帰的な監視を利用できない場合、サーバーは各検索の前に増分スキャンを実行します。

自動インデックス作成を無効にするには、次のようにします。

OBSIDIAN_SEMANTIC_AUTO_INDEX = "false"

その後、自分で index_vault { "mode": "incremental" } を呼び出します。従来の OBSIDIAN_SEMANTIC_STARTUP_INDEX=true も引き続きサポートされていますが、検索が行われなくても処理が実行されるため、デフォルトではありません。

検索品質の評価

クエリと期待されるパスを含む JSON ファイルを作成すると、同じ条件でキーワード検索、セマンティック検索、ハイブリッド検索を比較できます。

[
  { "query": "strong consistency at 1000 TPS", "expected_paths": ["03_Knowledge/QnA/Strong-Consistency-at-1000TPS.md"] }
]

npm run evaluate -- ./queries.json 5

このコマンドは Recall@K と MRR を報告します。ハイブリッド検索がキーワード検索のベースラインを測定可能なほど上回らない限り、ランキングの複雑さや埋め込みのコストを増やさないでください。

評価の前に、search_notes または index_vault でインデックスを更新してください。

開発

npm test
npm run pack:check

公開する前に、次のことを行ってください。

npm pack --dry-run

パッケージに data/、*.sqlite、またはプライベートな Vault ファイルが含まれていないことを確認してください。

ライセンス

MIT