Obsidian Brain

obsidian-brain

Obsidian Vaultに対して、Claude（およびその他のMCPクライアント）にセマンティック検索＋ナレッジグラフ＋Vaultの編集機能を提供する、スタンドアロンのNode MCPサーバーです。ローカルのstdioプロセスとして動作し、プラグインもHTTPブリッジもAPIキーもホスト先も不要です。Vaultのコンテンツがマシンの外に出ることはありません。

📖 詳細なドキュメント → sweir1.github.io/obsidian-brain 連携プラグイン → sweir1/obsidian-brain-plugin（任意 — active_note、dataview_query、base_queryが使えるようになります）

目次 — 選ばれる理由 · クイックスタート · 利用できる機能 · 仕組み · 連携プラグイン · トラブルシューティング · 最近のリリース

obsidian-brainが選ばれる理由

• Obsidianを起動しなくても動作 — Local REST APIベースのサーバーとは異なり、obsidian-brainは.mdファイルをディスクから直接読み取ります。Obsidianを閉じても、Vaultは単なるフォルダーです。
• Local REST APIプラグインは不要 — 基本機能を使うためにObsidian内へインストールするものはありません。
• RRFハイブリッド検索によるチャンク単位のセマンティック検索 — Markdownの見出し単位で埋め込みを生成し、Reciprocal Rank Fusionを使ってFTS5 BM25と統合します。該当するチャンクを見つけ、意味に基づいて順位付けします。
• PageRank＋Louvain＋グラフ分析を備えた唯一のObsidian MCPサーバー — Vault内で最も影響力のあるノート、橋渡しとなるノート、テーマのクラスターを検索できます。この機能を提供しているものは他にありません。
• 高品質なローカル埋め込みに対応するOllamaプロバイダー — 環境変数を1つ設定するだけで、qwen3-embedding:0.6b、nomic-embed-text、bge-m3などに切り替えられます。
• npxでまとめてインストール — リポジトリのクローンも、ビルドも、APIキーも、ホストされたエンドポイントも不要です。Vaultのコンテンツがマシンの外に出ることはありません。

クイックスタート

1行でインストール（macOS＋Claude Desktop）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sweir1/obsidian-brain/main/scripts/install.sh)"

HomebrewとNode 20以降がまだインストールされていない場合はそれらをインストールし、Claude Desktopに必要な/usr/local/binのシンボリックリンクを追加して、obsidian-brainの設定をclaude_desktop_config.jsonに統合します。Claudeのアクセスを有効にするため、Full Disk Accessの設定画面を開き、Claudeを再起動します。macOSのパスワード（Homebrewとシンボリックリンク用）とVaultのパスをそれぞれ一度入力するだけで、あとはすべて自動です。実行内容はこちらで確認できます：scripts/install.sh。

手動インストール

Node 20以降と、Obsidian Vault（または.mdファイルを含む任意のフォルダー）が必要です。Obsidian自体は不要です。

obsidian-brainをMCPクライアントに接続します。Claude Desktopの場合の例（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": ["-y", "obsidian-brain@latest", "server"],
      "env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
    }
  }
}

Claude Desktopを終了（macOSでは⌘Q）して、再起動します。これで完了です。

メモ

初回起動時に、サーバーがVaultを自動でインデックス化し、約34 MBの埋め込みモデルをダウンロードします。クライアントにツールが表示されるまで、30～60秒かかることがあります。2回目以降の起動はすぐに完了します。

ヒント

開発者ではありませんか？ macOSの手順ガイドでは、Homebrew、Node、GUIアプリのPATH修正、Full Disk Accessの設定を順に説明しています。

その他すべてのMCPクライアント（Claude Code、Cursor、VS Code、Jan、Windsurf、Cline、Zed、LM Studio、JetBrains AI、Opencode、Codex CLI、Gemini CLI、Warp）については、MCPクライアントへのインストールをご覧ください。

→ 環境変数の完全な一覧：設定
→ モデル／プリセット／Ollamaの詳細：埋め込みモデル
→ aaronsbのプラグインからの移行：移行ガイド

利用できる機能

目的別にグループ化された18個のMCPツール：

• 検索と読み取り — search、list_notes、read_note
• グラフの把握 — find_connections、find_path_between、detect_themes、rank_notes
• 書き込み — create_note、edit_note、apply_edit_preview、link_notes、move_note、delete_note
• ライブエディター（コンパニオンプラグインが必要）— active_note、dataview_query、base_query
• メンテナンス — reindex、index_status

→ 引数、例、レスポンスの形式：ツールリファレンス

仕組み

flowchart LR
    Client["<b>MCP Client</b><br/>Claude Desktop · Claude Code<br/>Cursor · Jan · Windsurf · ..."]

    subgraph OB ["obsidian-brain (Node process)"]
        direction TB
        SQL["<b>SQLite index</b><br/>nodes · edges<br/>FTS5 · vec0 embeddings"]
        Vault["<b>Vault on disk</b><br/>your .md files"]
        Vault -->|"parse + embed"| SQL
        SQL -.->|"writes"| Vault
    end

    Client <-->|"stdio JSON-RPC"| OB

取得も書き込みもSQLiteインデックスを経由します。読み取りはマイクロ秒単位で実行でき、書き込みは即座にディスクへ反映され、変更されたファイルを逐次再インデックスします。埋め込みはチャンク単位で行われます（見出しを考慮した再帰的チャンク分割により、コードブロックとLaTeXブロックを保持）。また、searchのデフォルトのhybridモードでは、チャンク単位のセマンティックランキングとFTS5 BM25をReciprocal Rank Fusionで統合します。

→ 技術解説 — stdio、SQLite、ローカル埋め込みを選んだ理由：アーキテクチャ → ライブウォッチャーの動作とデバウンス：ライブ更新 → 定期的な再インデックス（macOS launchd／Linux systemd）：定期インデックス作成（macOS） · （Linux）

コンパニオンプラグイン（任意）

任意のObsidianプラグインsweir1/obsidian-brain-pluginを使用すると、ライブのObsidianランタイム状態（アクティブなエディター、Dataviewの結果、Basesの行）がlocalhost HTTPエンドポイント経由で公開されます。インストールしてObsidianを起動すると、active_note、dataview_query、base_queryが利用可能になります。BRATでリポジトリID sweir1/obsidian-brain-pluginを指定してインストールしてください。

プラグインとサーバーは同じメジャー・マイナーバージョンで運用してください。サーバーv1.7.xにはプラグインv1.7.xを組み合わせます。パッチバージョンの違いは問題ありません。

→ セキュリティモデル、機能ハンドシェイク、Dataview／Basesの機能対応状況：コンパニオンプラグイン

トラブルシューティング

特によくある問題は次の4つです：

• Claude Desktopで**「Connector has no tools available」**と表示される — 通常、サーバーが起動時にクラッシュしています。~/Library/Logs/Claude/mcp-server-obsidian-brain.logを確認してください。解決方法：npm install -g obsidian-brain@latestを実行し、Claudeを終了（⌘Q）してから再起動します。
• ERR_DLOPEN_FAILED／NODE_MODULE_VERSIONの不一致 — better-sqlite3が異なるNode ABIに対してビルドされています。解決方法：PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3を実行します。
• Vault path not configured — VAULT_PATHが設定されていません。クライアント設定またはシェルのenvブロックで設定してください。
• npx経由で古いバージョンが読み込まれる（公開後もクライアントに以前のリリースが表示される）— npxのキャッシュが古くなっています。解決方法：rm -rf ~/.npm/_npxを実行してから、クライアントを再起動します。設定で@latestを指定しておくと、この問題を防げます。

→ 詳細なトラブルシューティングガイド（ウォッチャーが動作しない、インデックスが古い、複数のクライアントの実行、タイムアウト、埋め込み次元の不一致、ログの場所）：docs/troubleshooting.md

最近のリリース

• v1.7.24（2026-05-16）— embeddings.mdにBYOMの説明を追加＋開発依存関係を5件更新
• v1.7.23（2026-05-16）— BYOM Ollamaの自動プル制御＋ロガーの一斉更新＋SIGTERMの単体テスト
• v1.7.22（2026-05-15）— 構造化stderr（NDJSON）＋Ollamaの準備状態＋Dependabotのセキュリティ更新＋SIGTERMのドレイン統合テスト
• v1.7.21（2026-04-27）— install.shのVault選択機能を修正＋ollama pullの自動実行＋ドキュメント／テストの改善
• v1.7.20（2026-04-27）— Ollamaのプレフィックス検索バグを修正＋監査関連の改善13項目

→ 変更履歴の全文：docs/CHANGELOG.md · 今後の計画：docs/roadmap.md · ソースからビルド：docs/development.md

謝辞

このプロジェクトが着想やコードの参考にした obra/knowledge-graph と aaronsb/obsidian-mcp-plugin に感謝します。また、Xenova/transformers.js（ローカルでの埋め込み生成）、graphology（グラフ分析）、sqlite-vec（SQLite でのベクトル検索）にも感謝します。

関連プロジェクト

• apple-notes-brain — 関連プロジェクト macOS 上の Apple Notes 用 MCP サーバーです。Markdown の完全な双方向ラウンドトリップに対応し、読み取り、書き込み、検索を行えます。

ライセンス

Apache License 2.0 — Copyright 2026 sweir1.