obsidian-mcp-server

[!NOTE] このリポジトリはhuaqing0カスタムエディションであり、 cyanheads/obsidian-mcp-server v3.5.0 をApache-2.0ライセンスのもとでベースにしています。アップストリームのサーバーを維持しつつ、このエディションで使用されるローカルワークスペース、ボールト構造、ネイティブExcalidraw自動化を追加しています。以下のnpmおよびMCPBインストールリンクは引き続きアップストリームの配布物を指しています。このカスタムエディションは現在ソースのみの提供です。

ツール

31のツールが、ノートの内容、メタデータ、バックリンク、ネイティブExcalidraw自動化、ボールト構造の完全な管理をカバーし、さらにObsidianのコマンドパレットコマンド用の保護されたエスケープハッチも備えています。

obsidian_get_note

ボールトパス、アクティブファイル、または定期ノート（daily、weekly、monthly、quarterly、yearly）で指定されたノートを、4つの投影形式のいずれかで読み取ります。

• format: "content" — 生のMarkdown本文

• format: "full" — コンテンツ、frontmatter、タグ、ファイルメタデータ。includeLinks: true を渡すと、書かれた外部参照に加えて、Obsidianが解決した外部リンクとバックリンク（ボールト内部のみ — 外部URLはフィルタリングされます）を含めます

• format: "document-map" — 見出し、ブロック参照、frontmatterフィールドのカタログ

• format: "section" — 単一の見出し/ブロック/frontmatterセクション値（section が必要です）。見出しセクションにはその見出し配下の完全なサブツリーが含まれます

document-map投影を obsidian_patch_note と組み合わせて、パッチ適用前に編集対象を発見します。

obsidian_search_notes

mode で選択される最大3つの検索モード：

• text — 周囲のコンテキストウィンドウ付きの部分文字列マッチ。contextLength は各マッチの両側のコンテキスト文字数を制御します（デフォルト100。ヒットごとにより多くのコンテキストが必要な場合は増やしてください）。オプションの pathPrefix フィルタ（テキストモードのみ — 他のモードで pathPrefix を渡すと path_prefix_invalid_mode で拒否されます）。

• jsonlogic — path、content、frontmatter.<key>、tags、stat.{ctime,mtime,size} に対して評価されるJSONLogicツリー。カスタムの glob と regexp 演算子は、どちらも [PATTERN, VALUE] を受け取ります — パターンが先、次にフィールド参照：{"glob": ["Projects/*.md", {"var": "path"}]}。逆順にすると、ノート自身のフィールドがパターンとしてコンパイルされます：glob は何もマッチせず、regexp はフィールドがパースされる内容に対して即座に失敗します。これはバックリンクを表現する方法でもあります。専用のツールや上流のエンドポイントがないためです：{"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]} は、本文が Target Note をウィキリンクしているすべてのノートを返します。

• omnisearch — コミュニティの Omnisearch プラグインによるBM25ランキング検索。引用符で囲まれたフレーズ、-exclusion、path: / ext: フィルタ、タイポ許容、PDF + OCRカバレッジ（Text Extractor 経由）、AI Image Analyzer インデックスが有効な場合の視覚的概念画像マッチをサポートします。プラグインのHTTPサーバーが起動時に到達可能な場合のみモード列挙に存在します。上流は結果を50件にハードキャップします — クエリを絞り込んでより多くを表示してください（キャップに達した可能性がある場合、レスポンスは truncated: true を運びます）。

結果のページネーションは、MCP 2025-11-25 仕様に従い、不透明なカーソルで行われます。最初のページでは cursor を省略し、以降は直前のレスポンスの nextCursor を渡します。すべての結果には totalCount（パス・ポリシー適用後、ページネーション前）が含まれ、最後のページでは nextCursor が省略されます。テキストモードのヒットはさらに、ファイルごとに maxMatchesPerHit（デフォルト 10）で切り詰められるため、マッチの多い単一のノートがレスポンス予算を超えることはありません。切り詰められたヒットには truncated: true と totalMatches が付与されます。

obsidian_write_note

ファイル全体の誤上書きに対する保護デフォルト付きで、新規作成または外科的置換を行います。

• section なし — ファイル全体の PUT。overwrite: true が設定されていない限り、既存ファイルの上書きを拒否します。 file_exists（Conflict）エラーは、その場での編集に obsidian_patch_note / obsidian_append_to_note / obsidian_replace_in_note を推奨します。

• section あり — 指定された見出し/ブロック/frontmatter フィールドに対する置換付き PATCH で、ファイルの残りの部分には触れません。overwrite フラグはセクションモードでは無視されます。

出力は、呼び出しによって新しいファイルが作成された場合は created: true を報告し、既存ファイルを置換した場合やセクションを対象にした場合は false を報告します。すべての変更ツールは previousSizeInBytes と currentSizeInBytes も返すため、エージェントは誤った上書き、予期しない上流の動作、または誤ったファイルに到達したタイポパスを検出できます。

obsidian_append_to_note

アップサートとセクション追記を組み合わせたプリミティブで、上流の Local REST API の動作を反映しています。

• section なし — /vault/{path} への POST。ファイルが存在する場合は追記し、存在しない場合はコンテンツ全体を本文としてファイルを作成します。 出力の created: true は後者の分岐を示すため、エージェントはタイポパスや未作成のデイリーノートが静かに新しいファイルに変わったことに気づけます。

• section あり — 指定された見出し、ブロック参照、または frontmatter フィールドに対する追記付き PATCH。ファイルが存在している必要があります（存在しない場合、PATCH の事前チェックで note_missing がスローされます）。createTargetIfMissing: true を渡すと、既存ファイル内にセクション自体を作成できます。ブロック参照ターゲットは、区切り文字なしでブロック行に隣接して連結されます。区切りを入れたい場合は、content の先頭に改行を含めてください。

previousSizeInBytes は、アップサート作成分岐では 0、それ以外では実際のファイルサイズです。currentSizeInBytes は、操作後に上流から読み取った書き込み後のサイズです。差分を Buffer.byteLength(content) と比較すると、自動改行の注入や並行ライターを検出できます。

obsidian_patch_note

単一のドキュメントターゲットに対する外科的編集。

• operation: "append" — セクションの後に追加

• operation: "prepend" — セクションの前に追加

• operation: "replace" — セクションを置換

• ターゲット: 見出しパス、ブロック参照 ID、または frontmatter フィールド

見出しターゲットは、完全な Parent::Child パスまたは単独のリーフ名のいずれかを受け入れます。正確に 1 つの見出しに一致する単独のリーフは、書き込み前に完全なパスに展開され、レスポンスは編集が着地したロケーターをエコーします。複数の見出しに一致するリーフは ambiguous_section で拒否され、そのエラーデータには候補パスがリストされます。同じ解決は、section を指定した obsidian_write_note と obsidian_append_to_note にも適用されます。

パッチを適用する前に、format: "document-map" を指定した obsidian_get_note を使用して、存在するターゲットを発見してください。

obsidian_replace_in_note

obsidian_patch_note の構造的ターゲットに適合しない編集のための検索置換。ノートが取得され、置換が順次適用され（各置換は前の出力を参照）、結果が単一の PUT で書き戻されます。

scope は置換が実行される範囲を選択します。

• body（デフォルト）— YAML frontmatter ブロックの後のテキスト。ブロックは元のバイトから再添付されるため、バイト単位で同一に戻ります。

• frontmatter — --- フェンスの間の YAML のみ。フェンス自体は決してマッチしません。

• both — 各置換は frontmatter に対して実行され、次に body に対して実行されます。perReplacement[] は bodyCount と frontmatterCount を別々に報告します。

frontmatter がスコープ内にある場合、書き換えられた YAML は何かを書き込む前に再パースされます。プロパティのマッピングとしてパースできなくなった場合、呼び出しは frontmatter_invalid で失敗し、ノートは元のバイトを保持します。このチェックは、壊れる YAML（スカラー内の引用符なしの :、エイリアスに書き換えられたリストマーカー、余分な引用符）を捕捉します。ただし、整形式のままで別の意味になる編集（キーを改名する部分文字列の衝突や、スカラーの引用符を削除して型を変える置換など）は捕捉できません。単一プロパティへの型付き編集には obsidian_manage_frontmatter を優先してください。

置換ごとのオプション:

• useRegex — search を ECMAScript 正規表現として扱います。useRegex: true の場合、置換は $1 / $& キャプチャグループ参照を尊重します。

• caseSensitive — false の場合、大文字小文字を区別せずにマッチします。

• wholeWord — パターンを \b…\b でラップします。リテラルモードと正規表現モードの両方で機能します。

• flexibleWhitespace — search 内の任意の空白の連続を \s+ に置き換えます。リテラルモードのみ — useRegex: true の場合は効果がありません（直接表現してください）。

• replaceAll — false の場合、最初のマッチのみが置換されます。scope: 'both' の下では、その 1 つの置換は frontmatter でマッチした場合は frontmatter に、それ以外の場合は body に適用されます。

リテラルモードは置換内の $1 / $& をそのまま保持します — キャプチャグループ参照を展開するのは useRegex: true のみです。

obsidian_manage_tags

ノートのタグを追加、削除、または一覧表示します。2 つの表現のいずれかで動作し、デフォルトは標準の Obsidian frontmatter の場所です。

• location: 'frontmatter'（デフォルト）— frontmatter の tags: 配列のみ。ノート本文には触れません。

• location: 'inline' — 本文のインライン #tag 構文のみ。add はファイル末尾に #tag を追加します。

• location: 'both' — 両方の表現にわたるオプトインの調整。

add はタグが要求された場所に存在することを保証し、remove はタグを削除し、list は入力の tags 配列を無視します。フェンスで囲まれたコードブロック内のインライン #tag の出現は意図的にそのまま残されます。

インラインモードはノート本文のみを読み書きします — YAML スカラー内の # は frontmatter なので、インラインタグとしてリストされず、削除によって書き換えられることもありません。インラインタグの削除では、正確に 1 つの隣接する水平スペース（タグの前のスペース、または前にスペースがない場合はタグの後のスペース）だけが一緒に削除されます。ネストされたリストのインデント、4 スペースのインデントされたコードブロック、末尾の 2 スペースのハード改行、テーブルセルのパディングなど、他のすべてのバイトは保持されます。

obsidian_delete_note

ノートを完全に削除します。デフォルトではオフです。 tools/list に公開するには OBSIDIAN_ENABLE_DELETE=true を設定します。最初の呼び出しは削除ではなく確認リクエストで応答します — プロンプトにはファイルのバイトサイズが含まれるため、破壊的な影響範囲はユーザーが確認する前に見えます — そしてツールは回答とともに再試行されます。拒否またはキャンセルすると、呼び出しは cancelled で失敗し、DELETE は発行されません。destructiveHint アノテーションは、ホストの承認フローでも操作を表面化します。出力は previousSizeInBytes（削除時点のサイズ）と currentSizeInBytes: 0 を報告します。

確認は必須であり、フォールバックパスはありません。入力の往復を提供できないクライアントは削除を完了できません。他のすべてのツールは影響を受けません。

ヴォールト構造ツール

obsidian_create_folder はネストされたフォルダを冪等に作成します。obsidian_move_path は Obsidian のネイティブ FileManager を通じてファイルまたはフォルダを移動・名前変更し、欠落している宛先の親を作成し、Obsidian が内部リンクを更新できるようにします。obsidian_delete_folder はフォルダを再帰的に削除し、デフォルトでは Obsidian の設定済みゴミ箱動作を使用し、明示的に要求された場合は完全削除を行います。ノート削除と同様に OBSIDIAN_ENABLE_DELETE=true によってゲートされます。

obsidian_execute_command

ID によって Obsidian のコマンドパレットコマンドをディスパッチします（obsidian_list_commands で発見可能）。動作はコマンドに依存します — UI を開くコマンドもあれば、ファイルを削除したりヴォールトを閉じたりするコマンドもあります。

デフォルトではオフです。 OBSIDIAN_ENABLE_COMMANDS が未設定の場合、obsidian_execute_command とその発見パートナーである obsidian_list_commands の両方が disabledTool() でラップされます — tools/list には存在しませんが（LLM は呼び出せません）、オペレーター向けマニフェストには有効化のヒントとともに表示されます。

Related MCP server: Obsidian Tools MCP Server

パスポリシー（フォルダスコープの権限）

3 つのオプションの環境変数が、各ツールがターゲットにできるヴォールトパスをゲートします。デフォルト未設定 = 読み取りと書き込みの両方で全ヴォールト — 後方互換です。

マッチングは暗黙の再帰を伴うプレフィックスベースで、大文字小文字を区別せず、末尾のスラッシュは正規化されます。projects/ は projects/a.md、projects/sub/b.md などにマッチします。

書き込みパスは暗黙的に読み取り可能です — 見えないものを編集することはできません。したがって、ターゲットが READ_PATHS または WRITE_PATHS にマッチする場合、読み取りは成功します。

OBSIDIAN_READ_ONLY=true はパスチェックの前に短絡します — すべての書き込みツールとコマンドパレットのペアは起動時に disabledTool() でラップされ（tools/list には存在しません）、サービスに到達する書き込みは WRITE_PATHS に関係なく実行時に拒否されます。

拒否は型付きの path_forbidden（JSON-RPC コード Forbidden）で、アクティブなスコープが data.recovery.hint と data.activeScope にエコーされるため、LLM はサーバーログを調べずに自己修正できます。obsidian_search_notes の検索結果は READ_PATHS に対して静かにフィルタリングされます — 「N 件のヒットを隠しました」というインジケーターを表示するとゲートの目的が損なわれます。

タグの一覧表示はヴォールト全体にわたります。 obsidian_list_tags と obsidian://tags リソースはヴォールト全体のタグ名を集約し、OBSIDIAN_READ_PATHS によって狭められません — ゲートするパスがないため、読み取りスコープ外のタグ名（ノートの内容ではなく）が表面化する可能性があります。

起動バナーはアクティブなスコープをログに記録するため、オペレーターは起動時に設定を検証できます。

リソース

すべてのリソースデータはツールからも到達可能です — obsidian://vault/{+path} には obsidian_get_note、obsidian://tags には obsidian_list_tags。リソースは、特定のノートやヴォールトのスナップショットを会話に添付することを好むクライアントのために存在します。タグのペアはミラーではありません。obsidian://tags はスナップショットセマンティクスを維持し、上流のペイロードを全体かつソートなしで返します。一方、obsidian_list_tags はカウント順に並べ、上限を設けます。

機能

@cyanheads/mcp-ts-core をベースに構築:

• 宣言的なツールとリソース定義 — プリミティブごとに単一ファイル、フレームワークが登録と検証を処理

• 統一されたエラー処理 — ハンドラーがスローし、フレームワークがキャッチ、分類、フォーマット。ツールは型付きの errors[] コントラクトで失敗面を公開

• initialize でのサーバーレベルの instructions — デプロイ固有のオリエンテーション（アクティブパスポリシー、読み取り専用モード、コマンドパレットの切り替え）を、静的なツール/リソースカタログとともに仕様準拠のクライアントに提示

• HTTP トランスポートでのプラグ可能な認証: none、jwt、oauth

• オプションの OpenTelemetry トレーシングを備えた構造化ロギング

• STDIO および Streamable HTTP トランスポート

サーバー自体はステートレスです — すべてのツール呼び出しはローカル REST API に直接アクセスします。フレームワークのストレージバックエンド、リクエスト状態 KV、進行状況ストリームはここでは使用されません。Obsidian は単一ボールトであり、呼び出し間で永続化するものはありません。

Obsidian 固有:

• Obsidian Local REST API プラグインをラップ — 型付きクライアント、決定的なエラーマッピング

• 見出し、ブロック参照、frontmatter フィールドをまたぐセクション認識編集を、PATCH-with-target 操作で実現

• 両方の表現にわたるタグ調整: frontmatter の tags: 配列とインラインの #tag 構文（フェンスで囲まれたコードブロックはスキップ）

• 最大3つのモードでの検索: テキスト、JSONLogic、および（プラグインが到達可能な場合）BM25 ランキングの Omnisearch — MCP 2025-11-25 仕様に従ったカーソルページネーション、テキストモードではファイルごとのマッチクリッピング

• 破壊的な削除には必須の人間参加確認 — 両方のプロトコルリビジョンで提供されるマルチラウンドトリップの input_required ラウンドで、未確認のパスはツールを通じて存在しない

• ネイティブなボールト構造管理: フォルダの作成、Obsidian リンク更新を伴うファイル/フォルダの移動・名前変更、ゴミ箱または完全削除によるフォルダ削除

• ネイティブな Excalidraw Automation API 統合: 意味論的な作成/読み取り/追加/更新/削除、決定的なレイアウト、整合性検証、PNG プレビューエクスポート、冪等なノート埋め込み

• OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS によるフォルダスコープの読み書き権限と、グローバルな OBSIDIAN_READ_ONLY キルスイッチ — 拒否は型付きの path_forbidden で、アクティブなスコープがエラーデータにエコーバックされる

• オプトインのコマンドパレットペア (obsidian_list_commands + obsidian_execute_command) — OBSIDIAN_ENABLE_COMMANDS=true の場合のみ登録

• obsidian_get_note と obsidian_open_in_ui での寛容なパス解決 — 大文字小文字が一致しないパスを正規のファイル名に対して静かに再試行し、曖昧な大文字小文字の一致では Conflict をスローし、NotFound には近い一致のみが存在する場合に Did you mean: …? の提案を追加。obsidian_delete_note は意図的に除外 — 破壊的な操作はターゲットパスを静かに書き換えるべきではない。

はじめに

以下を MCP クライアント設定ファイルに追加してください。Obsidian Local REST API プラグインがボールトにインストールされ、有効化されている必要があります — 前提条件 を参照してください。

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

または npx を使用（Bun は不要）:

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。インラインの環境変数は一度きりの実行に有効です。繰り返し使用する場合は、値を .env にコピーして（.env.example を参照）、bun run start:http を実行してください。

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
# Server listens at http://127.0.0.1:3010/mcp by default

前提条件

• Bun v1.3.0 以上（または Node.js v24+）。

• Obsidian Local REST API プラグイン、v4.0.0 から v5.x までをボールトにインストールし、有効化。設定 → コミュニティプラグイン → Local REST API で API キーを生成し、OBSIDIAN_API_KEY にコピーしてください。プラグイン v6.0 では、このサーバーがセクションターゲット書き込みとドキュメントマップに固定している markdown-patch 1.x ワイヤーフォーマットが削除されます。

• 定期ノートターゲット（target: { "type": "periodic" }）には、さらにプラグイン v5.0.1 以前 が必要です — v5.0.2 で組み込みの /periodic/ ルートが削除されました。他のすべてのターゲットタイプは影響を受けません。

• 入力リクエスト（elicitation）に応答できる MCP クライアント。obsidian_delete_note は削除前に常に確認を求めるため、そのサポートがないクライアントはノートの読み書きはできますが、削除はできません。

• オプション: 11 の描画ツールを使用するには、Obsidian Excalidraw プラグインをインストールして有効化。他のノートおよびボールトツールには必要ありません。

• このサーバーはデフォルトで http://127.0.0.1:27123 を使用します。使用するには、プラグイン設定で 「非暗号化（HTTP）サーバー」 を有効にしてください。常時オン HTTPS ポートを使用する場合は、OBSIDIAN_BASE_URL=https://127.0.0.1:27124 を設定します。プラグインの自己署名証明書は OBSIDIAN_VERIFY_SSL=false（デフォルト）で処理されます。

インストール

1. リポジトリをクローン:

   git clone https://github.com/cyanheads/obsidian-mcp-server.git

2. ディレクトリに移動:

   cd obsidian-mcp-server

3. 依存関係をインストール:

   bun install

4. 環境を設定:

   cp .env.example .env
   # edit .env and set OBSIDIAN_API_KEY

設定

オプションのオーバーライドの完全なリストについては、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンのビルドと実行:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

• チェックとテストの実行:

bun run devcheck   # Lint, format, typecheck, security, changelog sync
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t obsidian-mcp-server .
docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server

Dockerfile はデフォルトで HTTP トランスポート、ステートレスセッションモードを使用し、/var/log/obsidian-mcp-server にログを出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます — それらを省略するには --build-arg OTEL_ENABLED=false でビルドしてください。

イメージはコンテナ内の0.0.0.0にバインドされます（Dockerのポートマッピングに必要）。自分のマシンの外から到達可能なデプロイでは、MCP_AUTH_MODE=jwt（MCP_AUTH_SECRET_KEY付き）またはoauthを設定してください。設定しない場合、リスナーはすべての呼び出し元に代わってOBSIDIAN_API_KEYをボールトに転送します。

プロジェクト構造

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.mdを参照してください。要約は以下のとおりです：

• ハンドラーがスローし、フレームワークがキャッチする — ツールロジック内でtry/catchを使用しない

• リクエストスコープのロギングにはctx.logを、テナントスコープのストレージにはctx.stateを使用する

• 新しいツールとリソースはsrc/mcp-server/*/definitions/index.tsのバレルを介して登録する

• 外部API呼び出しをラップする：生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落フィールドを捏造しない

コントリビューション

バグ、機能リクエスト、ドキュメントの不足はissueで報告してください — 何がアクション可能なissueになるかはCONTRIBUTING.mdを、私たちの協働方法についてはCODE_OF_CONDUCT.mdを参照してください。セキュリティレポートはSECURITY.mdを通じて送信し、公開issueには決して投稿しないでください。

小さく自己完結した修正のプルリクエストは歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細はLICENSEを参照してください。