MCP 対応ローカル REST API

スクリプト、ブラウザ拡張機能、AI エージェントに、安全で認証付きの REST API を通じて Obsidian ボールトへの直接アクセスを提供します。

• 対話型 API ドキュメント: https://coddingtonbear.github.io/obsidian-local-rest-api/

• Obsidian コミュニティページ: https://community.obsidian.md/plugins/obsidian-local-rest-api/

• できること

• クイックスタート

  • REST API

  • MCP クライアント

    • Claude Code

    • Claude Desktop

    • Cursor

    • その他のクライアント

• API 概要

• ノートのパッチ適用

  • 生コンテンツモード

• 特定セクションの指定

• 検索

• MCP（Model Context Protocol）

  • プロトコル改訂

  • クライアントの接続

  • 利用可能なツール

  • 利用可能なリソース

• API 拡張

  • 型付き拡張 API

  • 既知の拡張機能

• コントリビューション

• クレジット

できること

REST API または 内蔵の MCP サーバー を通じてボールトにアクセスできます。どちらのインターフェースも同じ中核機能を公開しているため、スクリプト、ブラウザ拡張機能、AI エージェントはすべて同じ言語で通信できます。

• ノートの読み取り・作成・更新・削除 — バイナリファイルを含むボールト内のあらゆるファイルに対する完全な CRUD

• 特定セクションへの外科的パッチ適用 — 見出し、ブロック参照、frontmatter キーを対象に、そのセクションだけをファイルの他の部分に触れずに追加・先頭挿入・置換・削除・移動

• ボールトの検索 — シンプルな全文検索、またはノートのメタデータ（frontmatter、タグ、パス、コンテンツ）に対する構造化 JsonLogic クエリ

• アクティブファイルへのアクセス — Obsidian で現在開いているノートの読み取り・書き込み

• コマンドの一覧表示と実行 — コマンドパレットを使った場合と同様に、任意の Obsidian コマンドをトリガー

• タグのクエリ — 使用回数付きでボールト全体のすべてのタグを一覧表示

• Obsidian でファイルを開く — Obsidian に特定のノートを UI で開くよう指示

• API の拡張 — 他のプラグインは API 拡張インターフェース を通じて独自のルートを登録可能

すべてのリクエストは自己署名証明書による HTTPS で提供され、API キー認証の背後で保護されています。

Related MCP server: Connect MCP

クイックスタート

プラグインをインストールして有効化したら、設定 → Local REST API を開いて API キーと証明書を確認します。

REST API

# Check the server is running (no auth required)
curl -k https://127.0.0.1:27124/

# List files at the root of your vault
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/

# Read a note
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md

# Read a specific heading (URL-embedded target)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append a line to a specific heading (PATCH with a JSON instruction)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

証明書の警告を回避するには、https://127.0.0.1:27124/obsidian-local-rest-api.crt から証明書をダウンロードして信頼するか、HTTP クライアントで直接その証明書を指定します。

MCP クライアント

MCP サーバーは https://127.0.0.1:27124/mcp/ で実行され、Authorization ヘッダー（例: Authorization: Bearer <your-api-key>）でベアラートークンを提供して認証する必要があります。プラグインは自己署名証明書を使用するため、OS またはクライアントで証明書を信頼するか、http://127.0.0.1:27123/mcp/ の平文 HTTP エンドポイントを使用する必要がある場合があります（設定 → Local REST API → HTTP サーバーを有効化 で有効にできます）。

Claude Code

Claude Code はネイティブの HTTP MCP サポートを備えています。サーバーを追加する最も簡単な方法は CLI を使用することです:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

または、プロジェクトルートの .mcp.json に手動で追加するか（プロジェクトスコープ）、claude mcp add --scope user でユーザー全体に設定します:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Desktop

Claude Desktop はリモート HTTP MCP サーバーをネイティブにサポートしていませんが、mcp-remote（Node.js が必要）でブリッジできます。claude_desktop_config.json に以下を追加します:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://127.0.0.1:27124/mcp/",
        "--header",
        "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

ファイルを保存したら Claude Desktop を再起動します。

Cursor

Cursor は Streamable HTTP MCP トランスポートをサポートしています。~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト固有）に以下を追加します:

{
  "mcpServers": {
    "obsidian": {
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

その他のクライアント

Streamable HTTP トランスポートをサポートする MCP クライアントは、Authorization: Bearer <your-api-key> ヘッダー付きで https://127.0.0.1:27124/mcp/ に接続できます。正確な設定形式については、お使いのクライアントのドキュメントを参照してください。

API 概要

完全なリクエスト/レスポンスの詳細については、対話型ドキュメント を参照してください。

ノートのパッチ適用

PATCH メソッドはこの API の最も便利な機能の 1 つです。ファイル全体を書き換えることなく、対象を絞った編集ができます。

JSON の命令を送信します。操作（replace、prepend、append、または delete）をスコープ（content、marker、markerAndContent、または parent）のターゲットに適用します。ターゲットとは、見出し（最上位から下方向への見出しテキストの配列として指定）、ブロック参照、または frontmatter キーです。ペイロードは content（文字列）、value（frontmatter 値用の JSON）、または destination（見出しの移動先）に格納されます:

# Replace the value of a frontmatter field
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"frontmatter","target":"status","operation":"replace","value":"done"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

content 文字列内の見出しレベルはターゲットに対して相対的です（先頭の # は直接の子になります）。警告（例: 見出しがレベル 6 を超えて再基準化された場合）は、Markdown-Patch-Warnings レスポンスヘッダー内のパーセントエンコードされた JSON として返されます。解析前に decodeURIComponent でデコードしてください。楽観的並行性制御には ifMatch（ドキュメントマップの version）を渡します。

注: 空白はライブラリが管理します。コンテンツはトリミングされ正規化された形式に縮小され（先頭と末尾の空行は意味を持ちません）、API 自体が挿入されたコンテンツが本文テキストに直面する場所に空行を供給するため、append や prepend は常に独自のブロックとして配置され、既存の段落に結合されることはありません。見出し行、既存の空行、各ドキュメントの間隔スタイルはそのまま保持されます。実際の例については対話型ドキュメントを参照してください。

既存のブロックを続行する場合（新しいブロックを開始する代わりに、たとえばリストを拡張する場合）、見出し命令に within を追加します。これはセクションの最上位本文ブロックの 1 つを選択するインデックスです（ドキュメント順で 0 始まり、末尾から数える場合は負の値。したがって -1 は最後のブロック）。within 編集は文字通りに結合されるため、結合部分は自分で管理します:

# Add an item to the last list under "Log" (the leading \n continues the block)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["Log"],"within":-1,"operation":"append","content":"\n- new item"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

markerAndContent スコープでは、prepend/append は代わりにインデックスされたブロックの隣に新しいブロックを挿入します。インデックスは位置ベースなので、最初にドキュメントマップを読み、編集を ifMatch と組み合わせてください。

生コンテンツモード

クライアントがリクエストボディにマークダウンをテンプレート化する場合（Shortcuts、Tasker、テンプレートからの curl）、そのコンテンツを命令に JSON エスケープするのは脆弱です。生コンテンツモードでは、命令のフィールドをボディから移動します。ターゲットは URL（または明示的な Markdown-Patch-Version: 2 を指定した Target-Type/Target ヘッダー）に、操作とオプションはヘッダーに配置され、ボディは生のペイロードとなり、JSON エスケープは不要です:

# Append a templated line under a heading — no JSON escaping anywhere
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Operation: append" \
  -H "Content-Type: text/markdown" \
  --data "- $TEMPLATED_CONTENT" \
  https://127.0.0.1:27124/vault/notes/daily.md/heading/Log

text/* ボディは content の運搬体、application/json ボディは value の運搬体、ボディなしは何も運びません（delete、または Destination ヘッダーによる移動）。Target-Scope、Within（命令の within インデックスを平文の整数として、例: -1）、Create-Target-If-Missing、Reject-If-Content-Preexists、If-Match ヘッダーで命令が完成します。ヘッダーのエンコーディングと詳細については対話型ドキュメントを参照してください。

古いヘッダー駆動の PATCH 形式をすでに使用していますか? その形式は命令を JSON ボディの代わりにリクエストヘッダーに分散させており、非推奨であり 6.0 で削除されます。引き続き動作します — Markdown-Patch-Version: 1 を送信するとオプトインできます（同じヘッダーで GET 時のレガシー :: 結合ドキュメントマップも選択されます）。この形式で提供されるレスポンスには Deprecation: true; sunset-version="6.0" ヘッダーが付きます。アップグレードするには、そのヘッダーを削除し、各ヘッダーを JSON ボディに移動します。対話型ドキュメントにフィールドごとのマッピング表があります。

完全な命令スキーマとオプションについては対話型ドキュメントを参照してください。

特定セクションの指定

ノートの特定の部分（見出し、ブロック参照、frontmatter フィールド）を、ファイル全体を取得または置換せずに読み取りまたは書き込みできます。これは GET、PUT、POST、PATCH リクエストで機能します（PATCH の場合は生コンテンツモードです — Operation ヘッダーを追加します）。

ファイル名の後に /<target-type>/<target> を追加します。 各ネストされた見出しレベルは独自のパスセグメントになるため、:: を含む見出しテキストはエスケープの必要がありません:

# Read the content under a specific heading
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Read a nested heading (one path segment per level)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/Work/Meetings

# Read a frontmatter field
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/frontmatter/status

# Replace the content of a heading via PUT (heading levels are normalized for you)
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append to a heading via POST
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Appended content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

サポートされているターゲットタイプ: heading、block、frontmatter。

GET では、Target-Scope ヘッダーがターゲットのどの部分を返すかを選択し、PATCH のスコープを反映します: content（デフォルト）、marker（ラベル — 見出しの生テキスト、ブロックの裸の ID、frontmatter キー）、または markerAndContent（ノード全体。PATCH の replace がそのスコープで消費するのとまったく同じ形。見出しサブツリーは独自の行を # Title として読み戻され、レベルは親に対して相対的です）:

# Read a whole section — heading line included — ready to edit and write back
curl -k -H "Authorization: Bearer <your-api-key>" \
  -H "Target-Scope: markerAndContent" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

非推奨: ヘッダーベースのターゲット指定。 以前のリリースでは Target-Type、Target、Target-Delimiter ヘッダー（および Target-Scope/Trim-Target-Whitespace）でセクションを指定していました。その形式は非推奨であり 6.0 で削除されます。Markdown-Patch-Version: 1 も同時に送信した場合のみ処理されます（その場合レスポンスには Deprecation ヘッダーが付きます）。それがない場合、それらのターゲット指定ヘッダーを提供すると 400 で拒否されます。1 つのリクエストで URL パスのターゲット指定とヘッダー形式の両方を提供すると 422 Unprocessable Entity が返されます。

検索

POST /search/simple/?query=your+terms は Obsidian の組み込みファジー検索を実行し、スコア付きのコンテキストスニペットとともに一致するファイル名を返します。

POST /search/ は JsonLogic 式（コンテンツタイプ application/vnd.olrapi.jsonlogic+json）を受け入れ、各ノートのメタデータ（frontmatter、タグ、パス、コンテンツ）に対して評価します。

MCP（Model Context Protocol）

[!NOTE] Obsidian用のサードパーティ製MCPサーバーはいくつか存在しますが、もう必要ありません。このプラグインには、Obsidian内で動作し、ボールトのライブメタデータ、アクティブファイル、コマンドパレットに直接アクセスできる組み込みのMCPサーバーが同梱されています。現在サードパーティ製サーバーを使用している場合は、このサーバーに切り替えるとより良い結果が得られる可能性があります。

このプラグインには、/mcp/ に組み込みのMCPサーバーが含まれており、AIエージェントやMCP互換クライアントがHTTPリクエストを手動で作成することなくボールトとやり取りできます。

トランスポート: Streamable HTTP — APIキー認証が必要です。

プロトコルリビジョン

このエンドポイントは、2026-07-28 リビジョンに加えて、2024-10-07 から 2025-11-25 までのセッションフルリビジョンを提供し、リクエストごとに選択するため、どちらのクライアントも共有できます。

2026-07-28 リビジョンはステートレスです。initialize ハンドシェイクもセッションもないため、プラグインは Mcp-Session-Id ヘッダーを発行も読み取りもしません。各リクエストは、params._meta に独自のプロトコルバージョンとクライアントIDを保持し、MCP-Protocol-Version、Mcp-Method、Mcp-Name ヘッダーでそれらを繰り返し、それぞれ独立して応答されます。クライアントは server/discover を呼び出して、サポートされているリビジョンと機能を事前に確認できます。

initialize リクエストで開始するクライアントには、ネゴシエーションしたセッションフルリビジョンが提供されます。ハンドシェイクは Mcp-Session-Id を返し、GET /mcp/ はそのセッションの通知ストリームを開き、DELETE /mcp/ はそれを終了します。セッションはこのパスにのみ存在し、ハンドシェイクの listChanged 機能を正確に保つ役割を担います。別のプラグインがMCPツールを登録または削除すると、すべてのライブセッションに通知され、2026-07-28 クライアントは subscriptions/listen ストリームでその通知を受け取ります。

クライアントの接続

MCPクライアントを https://127.0.0.1:27124/mcp/ に接続します。認証にはベアラートークンを使用します。APIキーは 設定 → Local REST API で確認し、次のように渡します:

Authorization: Bearer <your-api-key>

正確な設定構文はクライアントによって異なります。上記のクイックスタートの例を参照するか、Streamable HTTPリモートMCPサーバーに関するクライアントのドキュメントを確認してください。

[!WARNING] MCPサーバーに安全に接続するには、クライアントがプラグインの自己署名証明書を信頼する必要があります。https://127.0.0.1:27124/obsidian-local-rest-api.crt からダウンロードして信頼するか、127.0.0.1 のTLS検証をスキップするようにクライアントを設定できます。

環境で自己署名証明書を信頼できない場合は、設定 → Local REST API → HTTPサーバーを有効化 でHTTPエンドポイントを有効にしていれば、https://127.0.0.1:27124/mcp/ の代わりに http://127.0.0.1:27123/mcp/ を使用して安全でない接続を行うことができます。

利用可能なツール

利用可能なリソース

API拡張機能

他のプラグインは、このプラグインのサーバーに対して独自の認証付きルート、公開ルート、MCPツールを登録できます。ウォークスルーについては、拡張機能による独自のAPIルートの追加 を参照してください。

型付き拡張API

getAPI と、それが返すすべての型を取得するには、このパッケージを開発依存関係としてインストールします:

npm install --save-dev obsidian-local-rest-api

このパッケージは、obsidian、zod、@types/express をピア依存関係として宣言しています。その型が3つすべてを参照するためです。addRoute はexpressの IRoute を返し、addMcpTool はzodスキーマを受け取ります。npmがピア依存関係を自動的にインストールします。自分で固定する場合は、解決可能な状態に保ってください。これらがない場合、TypeScriptはエラーを報告せずにそれらの位置を静かに any に拡張するため、欠落型診断を抑制しているプロジェクトは、最も重要な箇所で型チェックが失われていることに気づきません。

import { getAPI, type LocalRestApiPublicApi } from "obsidian-local-rest-api";

const api: LocalRestApiPublicApi | undefined = getAPI(this.app, this.manifest, 2);

パッケージのエントリポイントは小さなスタンドアロンモジュールで、プラグインバンドルをビルドに取り込むのではなく、Obsidianのプラグインレジストリから実行中のホストプラグインを解決します。拡張APIバージョン（上記の 2）を渡すと、インストールされているホストが必要なサーフェスより古い場合に getAPI が ApiVersionUnsupportedError をスローします。省略すると、インストールされているものを受け入れて自分で機能検出します。プラグインがインストールされていないか、まだ読み込まれていない場合、getAPI は undefined を返します。

publicApi.d.ts は src/publicApi.ts から生成され、実装はコンパイル時にそれに対してチェックされるため、公開される型がプラグインが実際に提供するものから乖離することはありません。

既知の拡張機能

• Periodic Notes: 定期ノートのサポートを追加します

コントリビューション

CONTRIBUTING.md を参照してください。コアを変更せずに機能を追加したい場合は、代わりにAPI拡張機能の構築を検討してください。拡張機能は独立して開発・リリースできます。

クレジット

Vinzent03 の advanced-uriプラグイン に触発され、カスタムURLスキームの制約を超えて自動化オプションを拡張することを目的としています。