obsidian-knowledge-mcp

Obsidian vault の知識ノート (learnings / references / reviews などの markdown) を、全文読みせず vector + BM25 ハイブリッド検索で必要チャンクだけ取得するための MCP サーバーである。Claude Code の skill が抱える知識ファイルを検索対象とすることを想定している。

重要な前提

vault リポジトリは public 化しない前提である。 このサーバーは vault 内の知識本文をローカル sqlite (DB_PATH) にインデックスし、検索結果としてチャンク本文をそのまま返す。vault 本体・インデックス DB のいずれも公開してはならない。

アーキテクチャ

• チャンク分割: markdown を ## / ### 見出し単位で分割し、約 3200 文字を超える場合は段落境界でさらに分割する。frontmatter (skill / repo / domain / type) は yaml パッケージ (YAML 1.2) でパースし、chunk_meta テーブルへメタデータとして展開してフィルタに使う。各キーは複数値 (配列) を許容し、ノートは例えば domain に複数のドメインを宣言できる
• embedding: ollama の /api/embed (既定モデル bge-m3、1024 次元)
• 検索: sqlite-vec の vec0 による KNN (cosine) と FTS5 (tokenize='trigram') の BM25 を各 top 20 取得し、RRF (k=60) で統合する
• インデックス更新: サーバー起動時と毎 search_knowledge 呼び出し冒頭に mtime/size 突合の lazy 同期を行い、変化したファイルだけ再チャンク・再 embed する。検索した瞬間に必ず最新であることを保証する

前提

• Node.js v24 以上
• ollama が起動しており、embedding モデルを取得済みであること

ollama pull bge-m3

セットアップ

npm install
npm run build

Claude Code への登録例

claude mcp add obsidian-knowledge \
  --env VAULT_ROOT=/path/to/obsidian-vault \
  --env KNOWLEDGE_DIR=knowledge \
  -- node /path/to/obsidian-knowledge-mcp/dist/src/index.js

環境変数

変数	必須	既定値	説明
VAULT_ROOT	yes	-	検索対象のルートディレクトリ (絶対パス)
KNOWLEDGE_DIR	yes	-	VAULT_ROOT 配下の相対ディレクトリ。この配下の **/*.md がインデックス対象
OLLAMA_URL	no	http://localhost:11434	ollama サーバーの URL
EMBED_MODEL	no	bge-m3	embedding モデル名 (1024 次元であること)
DB_PATH	no	~/.local/share/obsidian-knowledge-mcp/index.db	インデックス sqlite ファイル。ディレクトリは自動作成される

MCP ツール仕様

search_knowledge

vector + BM25 のハイブリッド検索で関連チャンクを返す。知識ファイルの全文読みの代わりにまずこれを使う。

• 入力
  • query: string — 検索クエリ (日本語 / 英語)
  • filter?: { skill?, repo?, domain?, type? } — frontmatter 由来のメタデータで絞り込み。各 filter 値は文字列 1 つだが、判定は containment (そのノートが宣言する値集合に filter 値が含まれていればヒット) なので、domain を複数持つノートもいずれか一致すればヒットする
  • top_k?: number — 返却件数 (既定 8)
• 返却: 各ヒットの path / heading / score / チャンク本文。末尾に total bytes returned: N を付け、stderr にも返却バイト数をログする

read_knowledge

ノート全文を返す。search_knowledge のチャンクで足りない場合のみ使う。

• 入力: path: string — VAULT_ROOT からの相対パスまたは絶対パス。VAULT_ROOT 外へのパストラバーサルは拒否する

reindex_knowledge

mtime 差分検知を無視した強制再インデックス。

• 入力: scope?: string — VAULT_ROOT からの相対パス prefix。指定時はその配下のみ再構築する
• 返却: indexed files / chunks 数などのサマリ

CLI での動作確認

MCP を経由せず search_knowledge 相当を直接叩ける。

VAULT_ROOT=/path/to/vault KNOWLEDGE_DIR=knowledge \
  npm run dev-search -- "リトライの冪等性" --top-k 5

--skill / --repo / --domain / --type / --top-k オプションを受け付ける。

eval (golden query 評価)

eval/golden-queries.json に期待クエリを書き、hit@1 / hit@3 / hit@10 を計測する。

このファイルは期待する path や本文断片という形で vault 本文の抜粋を含むため gitignore してあり、リポジトリには入らない。スキーマの例として eval/golden-queries.example.json をコミットしてあるので、これをコピーして自分の vault に合わせて書き換える。

cp eval/golden-queries.example.json eval/golden-queries.json
VAULT_ROOT=/path/to/vault KNOWLEDGE_DIR=knowledge npm run eval

golden query の形式は次のとおりである。

[
  {
    "query": "一覧取得のたびに関連レコードを 1 件ずつ引いてしまう",
    "filter": { "repo": "my-repo" },
    "expect_path_contains": "learnings/db",
    "expect_content_contains": "eager loading"
  }
]

filter と expect_content_contains は省略できる。golden-queries.json が存在しない場合、npm run eval は評価をスキップして正常終了する。

既知の制約

• FTS5 の trigram tokenizer は 3 文字未満の語にマッチできない。クエリは空白区切りトークンのうち 3 文字以上のものだけを OR 結合して MATCH に使うため、2 文字の日本語単語 (例: 「設定」) は BM25 側では拾えない。その場合も vector 検索側が意味的に補完する
• frontmatter は --- 区切りブロックを yaml パッケージ (YAML 1.2) でパースする。ネストしたオブジェクト値は skill / repo / domain / type としては展開されず (空扱いになり警告を記録する)、YAML 構文エラーのノートは索引全体を落とさないよう frontmatter 無し扱いにフォールバックする
• domain などの frontmatter キーは配列で複数値を宣言できる (例: domain: [domain-a, domain-b])。search_knowledge の filter は containment で一致判定するが、MCP ツールスキーマ上の filter 値そのものは単一文字列のみを受け付ける (配列 filter は未対応)
• インデックス DB (DB_PATH) は vault から常に再生成できる派生キャッシュである。内部スキーマは PRAGMA user_version で管理しており、バージョンが変わると files / chunks / chunk_meta / vec_chunks / fts_chunks を全て作り直す (再起動時に自動で再インデックスされる)。このリポジトリのコードを旧バージョンへ戻す場合は DB ファイルの削除が必須である。旧コードは新スキーマの chunk_meta テーブルを認識せず、逆に新スキーマには旧コードが期待する chunks.skill / chunks.repo / chunks.domain / chunks.type 列が存在しない
• read_knowledge のパス検証は正規化ベースであり、VAULT_ROOT 内から外部を指す symlink は検出しない