Obsidian MCP Server

Obsidian MCP

MCP 対応アシスタントが、明示的に設定された Obsidian vault を安全に読み取り、変更できるローカルの Model Context Protocol サーバーです。

バージョン 2 は、MCP 2026-07-28 と 2025 年代のクライアントの両方をデフォルトでサポートし、Node.js 22 以降が必要です。Markdown ファイルを直接操作するため、Obsidian を開いておく必要はありません。従来のプロトコルと v1 の位置引数によるパス指定との互換性は非推奨であり、正確な移行手順を stderr に出力します。

重要

MCP クライアントは破壊的なツールを呼び出すことがあります。重要な vault はバックアップし、クライアントの権限確認プロンプトを確認し、同時に編集されるノートにはリビジョンの事前条件を使用してください。

クイックスタート

Node.js 22 以降が必要です。

node --version # v22 or newer

パッケージをグローバルにインストールせず、npx で実行します。メジャーバージョンを固定すると、将来のメジャーバージョンへ自動的に移行することなく、互換性のある 2.x アップデートを受け取れます。

npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault

同じコマンドを stdio 経由で起動するよう、MCP クライアントを設定します。

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/vault"]
    }
  }
}

または、パッケージをグローバルにインストールし、"serve" から始まる同じ引数を指定して "command": "obsidian-mcp" を使用します。

npm install -g obsidian-mcp@2

各 vault には .obsidian ディレクトリがすでに含まれている必要があり、絶対パスを使用して設定する必要があります。

どちらのプロトコル世代も、同じツール定義から提供されます。MCP クライアントが 2026-07-28 をネゴシエートすることを確認した後、"--legacy", "reject" を args に追加して、モダン専用モードを選択できます。

vault ID には小文字、数字、_、- を使用でき、先頭は英字である必要があります。アシスタントがツールに渡す値です。設定できる vault は最大 10 個です。--vault を繰り返して、複数の vault を公開できます。

obsidian-mcp serve \
  --vault work=/Users/me/Documents/WorkVault \
  --vault personal=/Users/me/Documents/PersonalVault

明示的な --vault は認可として扱われるため、ネットワーク、リムーバブル、隠しファイル、同期対象の場所も使用できます。どの場所にも同じ包含保護が適用されます。

設計原則

• vault へのアクセスは、プロセス起動時に明示的な許可リストで制限されます。
• すべてのツールパスは vault 相対で、セグメント単位でチェックされ、シンボリックリンクと予約済み状態から保護されます。
• ファイルの変更はジャーナルに記録され、競合がチェックされ、アトミックに置き換えられ、単一のトランザクションとしてロールバックされます。
• サーバーがネットワークインターフェースでリッスンしたり、テレメトリーを送信したりすることはありません。
• stdout は MCP メッセージ専用であり、構造化診断情報は stderr に出力されます。
• 結果には上限が設けられ、適宜ページ分割され、テキスト形式と構造化コンテンツの両方で利用できます。

ツール

ツール	目的
obsidian_list_vaults	ホストのパスを公開せずに、設定済みの Vault ID を一覧表示します。
obsidian_read_note	ノートの指定範囲のページを読み取り、SHA-256 etag を返します。
obsidian_create_note	上書きせずにノートをアトミックに作成します。
obsidian_edit_note	ノートの内容を末尾に追加、先頭に追加、または完全一致で置換します。
obsidian_delete_note	明示的な確認を行ったうえで、ノートを MCP のゴミ箱に移動するか、完全に削除します。
obsidian_move_note	ノートを移動または名前変更し、曖昧さのないバックリンクをトランザクション内で更新します。
obsidian_create_directory	Vault 内にディレクトリをトランザクション内で作成します。
obsidian_search_vault	内容、ファイル名、タグを、範囲が制限されたカーソルページネーションで検索します。
obsidian_add_tags	1 つ以上のノートにタグをアトミックに追加します。
obsidian_remove_tags	完全一致、階層指定、またはワイルドカードで選択したタグをアトミックに削除します。
obsidian_rename_tag	Vault 全体でタグ名をアトミックに変更します。
obsidian_manage_tags	同じ実装を使用する、タグ追加／削除の統合ワークフローです。

すべてのスキーマは、Zod から生成された厳密な JSON Schema 2020-12 コントラクトです。変更を伴う処理の結果にはトランザクション ID が含まれます。ツールの失敗時には、対処方法を示すエラーコードとともに isError: true が返されます。

読み取りと同時実行

obsidian_read_note は etag を返します。更新の消失を防ぐ必要がある場合は、編集、移動、削除の際に if_match として渡してください。タグの一括操作では expected_etags マップを指定できます。ノートが変更されている場合は、上書きせずに REVISION_CONFLICT を返します。

大きなノートは、パスと etag に紐付けられた不透明なカーソルを使ってページネーションされます。検索では、クエリとオプションに紐付けられた不透明なカーソルを使います。ツールのテキスト応答は 25,000 文字までに制限されます。

削除と復旧

デフォルトではゴミ箱を使用します。削除したノートのバイトデータとメタデータは、.obsidian-mcp/trash の下に分けて保存されます。メタデータがノートに挿入されることはありません。完全削除には、confirm_path が正規化された相対パスと完全に一致する必要があります。

トランザクションと復旧スナップショットは .obsidian-mcp/transactions に保存されます。完了したデータは 30 日間保持され、デフォルトでは 1 GiB を超えると古いものから削除されます。

obsidian-mcp serve --vault work=/path \
  --recovery-days 14 \
  --recovery-max-bytes 536870912

MCP サーバーの停止中に、完了したトランザクションを検査または復元します。

obsidian-mcp recovery list --vault work=/path
obsidian-mcp recovery restore --vault work=/path --id <transaction-id>

復旧時には、選択したトランザクション以降に変更されたコンテンツの上書きを拒否します。完全削除のスナップショットはコミット後に消去され、復元できません。

パスとファイルシステムの安全性

サーバーは次の処理を行います。

• 設定された Vault のルートを正規化し、重複したルートや入れ子になったルートを拒否します。
• 絶対パス、UNC パス、Windows ドライブパス、NUL、バックスラッシュ、空のパス、ドットセグメントを含むツールパスを拒否します。
• .obsidian、.obsidian-mcp、.git、.backup、.trash をツールからのアクセス対象外として予約します。
• 既存の対象と、新しい対象の最も近い既存の祖先を確認します。
• シンボリックリンク、ジャンクション、再解析ポイントのパスを拒否し、スキャン時にはそれらをスキップします。
• ファイルシステムの検証にシェル実行を使用しません。
• UTF-8 を厳密にデコードし、不正なバイトを暗黙に置き換えません。

プロセスには、設定された各 Vault への読み取りおよび書き込みアクセスが必要です。obsidian-mcp doctor --vault id=/path は起動準備状態と復旧状態を検証します。

リンクとタグの動作

移動では、Obsidian Wikilinks、埋め込み、Markdown リンク、エイリアス、URL エンコードされたリンク先、見出し、ブロックアンカーが認識されます。リンクは、移動元のノートを一意に特定できる場合にのみ書き換えられます。曖昧なリンクは報告され、変更されずに残ります。削除時は、backlink_action: "mark_broken" が指定されない限り、バックリンクは保持されます。

タグは Obsidian の大文字と小文字を区別しないルールに従い、Unicode、絵文字、_、-、/、ネストされたタグに対応します。フロントマターのタグは YAML リストとして記述されます。インラインタグの処理では、フェンス付きコード、インラインコード、HTML コメントは無視されます。ワイルドカードには、正規表現ではなく上限付きマッチャーを使用します。

開発

npm ci
npm run typecheck
npm test
npm run build
npm run ci

各ツールは、src/tools/<tool>/index.ts に型付き定義を持ちます。src/tools/index.ts の小さなレジストリが、共通の MCP 登録とレスポンスの動作を適用します。ファイルシステム、トランザクション、Markdown、リンク、検索の動作は、再利用可能なユーティリティに実装されています。新しいツールでは、すべてのパスに VaultFs を使用し、変更には TransactionManager を使用する必要があります。また、厳密な入出力スキーマ、構造化された結果、アノテーション、セキュリティテストと統合テストも必要です。

1.x からの移行については MIGRATING.md、脆弱性の報告については SECURITY.md を参照してください。

起動エラーと互換性に関する警告は、安定したコード、検出された問題、正確な修正方法、検証手順、該当する移行セクションへのリンクとともに、stderr にのみ出力されます。サーバーが表示されない場合は、MCP クライアントのログでコードを確認し、診断リファレンスを参照してください。

ライセンス

MIT