Obsidian MCPでClaude CodeにVaultを読み書きさせる方法

ObsidianのMCPサーバーとは何か

結論から書くと、Obsidian本体が出している公式のMCPサーバーはありません。ClaudeからVaultを読み書きするなら、コミュニティプラグインのLocal REST APIを入れます(ストア上の表示名は「Local REST API with MCP」)。その/mcp/エンドポイントにつなぐのが最短です。Claude Codeならclaude mcp add --transport httpの1コマンド、Claude Desktopならmcp-remoteを挟む設定になります。手順は後半で順に示します。

Vaultを読み書きするMCPサーバーは、いずれもコミュニティが作ったプラグインや外部ツールです。仕組みは共通していて、Obsidian内(または隣接プロセス)にローカルのHTTPサーバーを立て、そこにMCPクライアントとしてClaudeを接続します。通信はすべて127.0.0.1宛てのループバック接続で完結し、Vaultの中身をどこかの外部クラウドへ送信する設計にはなっていません。クラウド上のアウトライナーであるRoamは、公式コネクターで接続する別の方式です(Roam Research連携)。

実装は大きく4つあります。ノート単体の検索や差分編集だけでなく、フロントマターの取得やバックリンクの追跡までツール化されているものもあり、選ぶ実装によって扱える操作の幅がかなり変わります。この記事では、実装ごとの選び方の判断材料と、代表的な2つの導入手順、そして古いブログ記事を参考にすると踏みやすい落とし穴をまとめます。

導入前に確認すること

どの実装を選んでも、次の3つは共通の前提です。

• Obsidianアプリ本体と、MCPで公開したいVaultがローカルに存在すること
• Claude CodeまたはClaude Desktopなど、MCPクライアントとして動く環境
• 実装によってはLocal REST APIというコミュニティプラグインの追加インストールが必要

3つ目が地味に重要です。後述する4実装のうち2つは、この「Local REST API」プラグインが提供するREST APIの上に乗る形で動きます。つまりObsidianのプラグイン設定を1回で済ませられず、2つのプラグイン(または1つのプラグイン+1つの外部プロセス)を組み合わせることになります。

どの実装を選ぶか

実装ごとの性格がかなり異なるため、人気度の目安や更新頻度も含めて並べます。Leonezz版はGitHubのスター数が4と少ないため、ストアのダウンロード数で示しており、他3件と指標が異なります。

この中で実質的な第一候補は上の2つです。Local REST APIの定番は、以前は2段構成でした。Local REST APIでVaultをREST公開し、別途Pythonのmcp-obsidianを起動してAPIを叩く形です。今はLocal REST APIプラグイン単体で/mcp/エンドポイントが立ち上がります。プラグインのREADMEも「サードパーティのMCPサーバーはもう必要ない」と明記しており、既存のPythonブリッジからの乗り換えを推している状態です。

mcp-obsidianを選ぶ理由が残るとすれば、すでにuvx経由のPython環境を他のMCPサーバーでも使っていて構成を揃えたい場合や、stdioトランスポートで完結させたい場合くらいです。

Local REST APIプラグインでMCPを使う(推奨)

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

claude mcp addの実際の挙動を、v2.1.285で作業用の空ディレクトリに--scope projectを付けて確かめました。ダミーのキーを渡しており、Obsidianには接続していません。

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

Added HTTP MCP server obsidian with URL: https://127.0.0.1:27124/mcp to project config
Headers: {
  "Authorization": "[REDACTED]"
}
File modified: <作業ディレクトリ>/.mcp.json

画面には末尾のスラッシュが落ちたURLと、伏せ字のヘッダーが出ます。ところが生成された.mcp.jsonを開くと、URLは/mcp/のまま、キーは平文で書かれていました。

プロジェクト単位で.mcp.jsonに書く場合は次の形になります。生成物もほぼ同じ形です。

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

接続できると、Vault操作のツール一式が使えるようになります。中心はvault_read(読み取り)・vault_write(新規作成・上書き)・vault_patch(見出しやフロントマターの部分編集)です。検索はsearch_query(JsonLogicによる構造化検索)とsearch_simple(全文検索)があります。vault_get_document_mapは、見出し・ブロック参照・フロントマターのフィールドを一覧で返します。ほかに追記(vault_append)、移動・複製(vault_move・vault_copy)、削除(vault_delete)があります。開いているノートのパスはactive_file_get_pathで分かります。vault_deleteは既定でゴミ箱に移すので、誤って消しても戻せます。

mcp-obsidianに無い機能の代表が、command_executeです。Obsidianのコマンドパレットに登録された任意のコマンドをIDで実行でき、テンプレートプラグインや他プラグインが足したコマンドも対象になります。「今日のデイリーノートを開いてテンプレートを適用する」のような、ファイル操作を超えた依頼が通ります。tag_listでタグの使用回数を棚卸しでき、ノートの整理を任せたいときに向きます。

添付ファイルの扱いにも注意点があります。vault_readはUTF-8として読めないファイルを拒否し、vault_writeとvault_appendは画像・音声・動画・PDFなどの拡張子への書き込みを拒否します。テキストとして読み書きして添付を壊す事故を、ツール側で先に止める設計です。添付はvault_read_binaryで読みます。

• ラスター画像は長辺1568pxに縮小され、モデルが実際に画像を見られる形で返ります。課金は容量でなく画素数に応じ、数MBの写真でも数千トークン程度です
• 縮小後も512KiBを超える画像や、画像以外のファイルは署名付きダウンロードURLで返ります
• 署名付きURLを無効にしている場合、512KiB未満は埋め込みで返り、それを超えるファイルは拒否されます

512KiBという小さな上限は、トークン代だけが理由ではありません。約1MB以上のBase64を返すとObsidianのレンダラーが落ち、プラグインのHTTPサーバーごと止まった例があるため、余裕を持って下げてあるとREADMEに書かれています。署名付きURLは既定で有効で、有効期間は300秒です。

Claude DesktopからLocal REST APIのMCPにつなぐ

Local REST APIのMCPはリモートHTTPで、Claude DesktopはリモートのHTTP MCPサーバーを設定ファイルから直接は扱えません。READMEはmcp-remote(Node.jsが必要)を間に挟む方法を示しています。

Desktop向けの設定は次のとおりです。

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

設定ファイルの場所はOSで違います。macOSは~/Library/Application Support/Claude/claude_desktop_config.jsonです。Windowsは%APPDATA%\Claude\claude_desktop_config.jsonです。stdioで足りるmcp-obsidianなら、この中継は要りません。

mcp-obsidian(Python版)で接続する場合

すでにLocal REST APIプラグインを別用途で使っていて、Pythonのブリッジ経由に慣れている場合はこちらも選べます。前提としてLocal REST APIプラグインのインストールとAPIキー取得は同じく必要です。

uvx mcp-obsidian

mcp-obsidianはstdioで動くため、Claude Desktopの設定ファイル(claude_desktop_config.json)にそのまま書けます。

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>"
      }
    }
  }
}

OBSIDIAN_HOSTを省略すると127.0.0.1、OBSIDIAN_PORTを省略するとLocal REST APIの既定ポート27124が使われます。動作環境はPython 3.11以上で、依存するmcpパッケージのバージョンを1.1.0以上2.0未満に固定する必要がある点だけ注意してください。mcp>=2.0を入れると、list_toolsハンドラの実装方式が変わっているためインポート時にエラーで落ちます。

MCP内蔵のもう一つのプラグイン(Leonezz版)という選択肢

Obsidianの公式Community Pluginsストアには、Local REST APIとは別に「MCP Server」という名前のプラグインも単独で掲載されています。作者はleonezzで、community.obsidian.mdのストアから直接インストールできます。ただしダウンロード数は1,000件台、開発ステータスは「Beta」とプラグイン自身が明記しており、Local REST APIやmcp-obsidianに比べると採用実績は薄めです。

機能面の特徴は4つあります。現在開いているノートを返すget_active_fileで、「今読んでいるファイルの続きを書いて」のような依頼に対応できます。パスやタグ単位でアクセスを制限するブラックリストがあります。接続中のMCPセッションはlist_sessionsで確認できます。既定でBearerトークン認証が有効になっており、開発用途に限りローカルで認証を無効化することもできます。小規模なVaultで試験的に使う分には選択肢になりますが、更新頻度と実績を考えると、本記事で優先して薦めているLocal REST APIかmcp-obsidianのどちらかから始めるほうが手堅い選択です。

よくあるつまずき

• 古いブログ記事の手順で"Plugin Not Working"になる: obsidian-mcp-tools(jacksteamdev)は2026年5月にアーカイブされたプロジェクトです。開発者自身が「Obsidianを使わなくなったので身を引く」と明記し、ストアに代替プラグインが複数あると案内しています(特定のプラグインは勧めていません)。このプラグインを紹介する記事を見かけても、新規に導入するなら選ばないほうが安全です
• ポート番号を混同する: Local REST APIは既定でHTTPSが27124、HTTPが27123です。mcp-obsidianのOBSIDIAN_PORTにHTTP用の27123を指定してしまうと接続に失敗します
• 証明書エラーで接続できない: Local REST APIプラグイン内蔵のMCPはプラグインが作るローカルCAの証明書を使うため、クライアントによってはTLS検証で弾かれます。証明書を信頼できない環境では、平文HTTPエンドポイント(27123)に切り替えるのが手早い回避策です
• uvxのパスが見つからない: Claude Desktopがuvxコマンドを検出できないことがあります。which uvxでフルパスを確認し、commandにそのまま指定すると解決します
• APIキーが.mcp.jsonに平文で残る: claude mcp add --scope projectは、画面で伏せ字にしたAuthorizationヘッダーを、.mcp.jsonには平文で書きます。共有リポジトリにコミットする前に、"Authorization": "Bearer ${OBSIDIAN_API_KEY}"のように環境変数の参照へ置き換えます。${VAR}はurlとheadersでも展開されます。ANTHROPIC_API_KEYのようにClaude Code自身やクラウドの認証情報にあたる名前は空として読まれるので、OBSIDIAN_API_KEYのように別の名前で持ちます
• 更新後に古いスクリプトのPATCHが失敗する: 4.0.1で、2.x時代のPATCH形式(Heading・Content-Insertion-Positionヘッダー)が廃止されました。5.0.0(2026年7月24日)ではPATCHの処理系が入れ替わり、Target-Type・Target・Target-Delimiterヘッダーで対象を指す3.x形式も非推奨です。この形式はMarkdown-Patch-Version: 1ヘッダーを付けたときだけ処理され、付けないと400で拒否されます。6.0で削除される予定です。REST APIを直接叩く自作スクリプトは、JSON本文で指示を送る形に直します。例は{"targetType":"heading","target":["見出し"],"operation":"append","content":"..."}です。本文を生のMarkdownで送る方式もあり、URLパスを/vault/<ノート>/heading/<見出し>とし、Operationヘッダーで操作を指定します。テンプレートから本文を組むスクリプトにはこちらが向きます
• 書き込み系ツールで意図しないファイルが上書きされる: vault_writeはファイル全体を置き換えます。見出し単位やフロントマターの一部だけ変えたいときはvault_patch(Local REST API版)やpatch_content(mcp-obsidian版)を使い、全文置換を避けます

まとめ

新規に導入するなら、追加のプロセス管理が要らないLocal REST API単体から始めると構成が軽く済みます。stdioやuvxで他のMCPサーバーと構成を揃えたいなら、mcp-obsidianが残ります。.mcp.jsonをリポジトリで共有するなら、APIキーは環境変数の参照にしておきます。

Claudeとのやり取りの中でノートの内容がモデルに渡ること自体は避けられないため、機密情報を含むVaultを接続する場合は、Claude CodeのMCP権限設定でツールごとのアクセスを絞ることも検討してください。MCPの基礎から確認したい場合はMCPとは何か、claude mcp addのスコープや認証の詳細はClaude Code MCP設定ガイドにまとめています。既存ツールにない独自の操作を追加したい場合は、Claude CodeでObsidianプラグインを開発する手順でサンプルプラグインの拡張方法を扱っています。