Claude Code × ESP32｜ESP-IDF 6.0 の MCP サーバ活用ガイド

🧭 はじめに：「コマンドを写経する」から「頼んで実行してもらう」へ

ESP-IDF で開発していると、AI アシスタントに聞いた idf.py コマンドをチャットからターミナルへコピペし直す、という往復が地味に多くなります。ターゲットを変えて、ビルドして、書き込んで、ログを見て、また聞く。この「写経」の部分だけは、これまで手作業でした。

ESP-IDF 6.0 で加わった MCP サーバは、この往復を閉じるための仕組みです。Claude Code のような AI クライアントに「ターゲットを ESP32-C6 にしてビルド、つながっているデバイスに書き込んで」と頼むと、クライアントがサーバ経由で idf.py の操作を直接実行する——というのが、この機能のねらいです。

この記事では、何ができて・どう繋ぎ・どこで詰まるのかを、Espressif 公式の手順にもとづいて整理し、接続からツール呼び出し・実機書き込みまでを実機で確かめた結果を反映しました（検証環境と結果は末尾の「🔧 実機で確認した結果（2026-07-30）」にまとめています）。「導入すべきか」という判断の話ではなく、「使うとどこが楽になり、どこは変わらないか」という実務の地図として読んでください。

ESP-IDF 6.0 そのものの変更点（レガシードライバの全廃など）は別記事にゆずり、本記事はその 6.0 で新しく使えるようになった機能の1つ、という位置づけにしぼって進めます。

🔌 そもそも MCP とは

ESP-IDF まわりで公式に用意されている MCP サーバは、大きく2つあります。手元のプロジェクトを操作するローカルサーバと、公式ドキュメントを検索するリモートサーバです。全体像は次のようになります。

以下、まずローカルの Tools サーバから見ていきます。

🧰 ESP-IDF 6.0 の「Tools ローカル MCP サーバ」でできること

ESP-IDF 6.0 の目玉のひとつが、idf.py に組み込まれた Tools ローカル MCP サーバです。stdio でやり取りするローカルサーバとして動き、プロジェクトの操作と状態を MCP クライアントに公開します。

公開されるものは、実行できるツールと、読み取り専用のリソースに分かれています。

つまり、AI クライアントは project://status で「いまのターゲットとビルド状態」を読み、set_target や build_project で「操作」を行える、という設計です。読む側と実行する側が明確に分かれているのが要点です。

実際に接続すると、Claude Code 側からは公開ツールが次のように一覧できます（実機の表示）。

🔗 Claude Code につなぐ

接続は、大きく ①環境を用意する → ②サーバを起動できる状態にする → ③クライアントに登録する → ④依頼する、の流れです。

① 環境を用意する（EIM で mcp 機能まで入れる）

Tools ローカル MCP サーバを使うには、ESP-IDF v6.0 以降を「mcp 機能つき」で入れておく必要があります。ここが最初の関門なので、実機（Windows 11 Pro）で確かめた手順を残します。

EIM（ESP-IDF Installation Manager）は 6.0 で導入された新しいインストーラです。Windows では winget で入れるのがいちばん手軽でした。導入されるのは GUI 版（確認時は 0.17.1）ですが、GUI 版は CLI 機能を完全に内蔵しているため、そのまま eim コマンドが使えます（CLI 専用版を別途入れる必要はありませんでした）。

winget install Espressif.EIM

mcp 機能を後付けするには、feature を明示して入れ直します（2回目はツールキャッシュが効いて約3.5分でした）。

eim install --idf-versions v6.0.2 --idf-features mcp --non-interactive true

mcp feature が要求する Python パッケージは tools\requirements\requirements.mcp.txt に定義されていて、中身は mcp[cli] です。

python -m pip install "mcp[cli]<2"

環境構築の全体像は VS Codeで始めるESP-IDF環境構築ガイド｜最小構成でHello Worldまで が参考になります（そちらは v5.5.2 前提ですが、拡張機能やステータスバーの考え方は共通です）。

② サーバの起動コマンド

MCP サーバは idf.py のサブコマンドとして起動します。

# ESP-IDF 環境がすでに有効な状態なら
idf.py mcp-server

# EIM 経由で起動する（推奨）
eim run "idf.py mcp-server"

# プロジェクトの外から場所を指定して起動する
idf.py -C /path/to/your/project mcp-server

起動に成功すると、次の1行が出てそのまま入力待ち（待ち受け）になります。無言で固まるわけではないので、この行が出れば起動は成功しています。

MCP Server running on stdio...

③ Claude Code に登録する

Claude Code へは、stdio サーバとして登録します。実機では次のコマンドがそのまま通り、/mcp で esp-idf-eim が connected（4 tools） と表示されました。

claude mcp add --transport stdio esp-idf-eim -- eim run "idf.py -C <プロジェクトのパス> mcp-server"

-C <プロジェクトのパス> で対象プロジェクトを明示できます（--help で確認済み。後述の IDF_MCP_WORKSPACE_FOLDER の代わりになります）。eim run に渡した複数の引数は、正しく連結されて idf.py に届きました。

Cursor や VS Code の場合は、設定ファイルに JSON で書きます（Cursor は .cursor/mcp.json、VS Code は .vscode/mcp.json）。

{
  "mcpServers": {
    "esp-idf-eim": {
      "command": "eim",
      "args": ["run", "idf.py mcp-server"],
      "env": { "IDF_MCP_WORKSPACE_FOLDER": "${workspaceFolder}" }
    }
  }
}

④ 依頼する

登録できたら、あとは自然言語です。たとえば「ターゲットを ESP32-C6 にして、ビルドが通るか確認して」と頼めば、クライアントは set_target と build_project を順に呼び出します。実機でも、ツールが呼ばれて処理そのものは最後まで走ることを確認しました。ただし現状は「処理は成功するのに完了応答が返らない」という別の問題があり、この点は後述の「🔧 実機で確認した結果（2026-07-30）」で正直に扱います。どのチップを選ぶかで迷っている場合は、ESP32 シリーズの選び方｜S3・C3・C6・H2・P4 の違いと使い分け で用途からモデルを決めてからにすると、ターゲット指定で迷いません。

📚 もう一つの公式サーバ：ドキュメント MCP（リモート）

ローカルの Tools サーバとは別に、公式ドキュメントを検索するためのリモート MCP サーバも用意されています。なお、このリモートサーバは今回の実機検証の対象外で、以下の記載は Espressif 公式ドキュメントにもとづくものです。

• 種類 — リモートの HTTP サーバ（起動するローカルプロセスはありません）
• エンドポイント — https://mcp.espressif.com/docs
• 公開ツール — search_espressif_sources(query, language)。最新の Espressif ドキュメント（英語・中国語）に対して意味検索を行います

Claude Code へは HTTP サーバとして登録します。

claude mcp add --transport http espressif-docs https://mcp.espressif.com/docs

これを入れておくと、AI クライアントが当てずっぽうではなく、公式ドキュメントを根拠に答えを組み立てやすくなります。Tools サーバ（操作）とドキュメントサーバ（根拠）は、役割が違うので併用すると相性がいい組み合わせです。

公式が用意している MCP サーバは、ハブページ mcp.espressif.com にまとまっています。上記2つのほか、クラウド側の ESP RainMaker 用サーバなどもここから辿れます。

⚠️ 使う前に知っておきたい注意点

• 実行できる操作は、サーバが公開しているものだけ — Tools サーバが公開しているのは、いまのところターゲット設定・ビルド・書き込み・クリーンと、状態の読み取りです。デバッグや回路の問題を解決してくれるわけではありません。 便利になるのは「操作の往復」であって、設計判断そのものではない、という線引きが大事です
• 重いツール呼び出しは、現状 Windows で「完了応答が返らない」ことがある — 実機検証で 4/4 回再現しました。ビルドや書き込みといった処理そのものは成功しているのに、MCP のタスクが完了扱いにならず待ち続ける症状です。詳細と回避策は後述の「🔧 実機で確認した結果（2026-07-30）」にまとめました
• 書き込みは実機に届く — 前述のとおり flash_project は実デバイスへの書き込みです
• 環境変数を引き継がない — IDF_MCP_WORKSPACE_FOLDER の件。ローカルサーバ特有のつまずきどころです
• MCP は仕様が動いている最中 — 下のワード解説を参照

🧭 どこで効いて、どこで効かないか

最後に、実務目線での効き所を整理します。

• 効くところ — ターゲット切り替え・ビルド・書き込み・状態確認といった反復操作の往復。「聞く → コピペ → 実行 → また聞く」の写経が消えます。特に、複数チップを行き来しながら試す局面で楽になります
• 効かないところ — 原因究明そのもの。ビルドエラーの本質的な修正や、配線・電源・タイミングの問題は、これまでどおり自分で切り分ける領域です。MCP サーバは「手を動かす部分」を代行してくれるだけで、「考える部分」を肩代わりするものではありません

この線引きさえ押さえておけば、MCP サーバは環境が整っているほど効いてくる道具です（現状の制約は後述の実機結果のとおりで、当面は eim run でのシェル直行が現実解になります）。まだ 6.0 に上げていないなら、レガシードライバの全廃など上げるときの注意点を先に把握してから移行するのが安全です。

🔧 実機で確認した結果（2026-07-30）

ここまでの接続手順を、実機で最後まで通してみました。結論から言うと、方向性は本物で「実処理はもう動く」段階です。ただし Windows では、重いツール呼び出しで「処理は成功するのに完了応答が返らない」問題があり、実用は今後のパッチ待ち、というのがこの時点（2026-07-30）での率直なところです。以下、成功したところ・詰まったところ・回避策を、事実と仮説を分けて残します。

検証環境

• OS — Windows 11 Pro
• EIM — 0.17.1（winget Espressif.EIM）
• ESP-IDF — v6.0.2（既定の導入先 C:\esp\v6.0.2\esp-idf）
• mcp（Python パッケージ） — 1.29.0（前述のとおり 2.0 から落としたもの）
• 実機 — ESP32-S3（PSRAM 8MB）、ポート COM5
• クライアント — Claude Code（stdio 登録）

動いたところ

接続・ツール一覧の取得・実機への書き込みまで、やりたいことは一通り実機で成立しました。

★ 詰まったところ：ツールは動くのに「完了応答」が返らない

いちばんの問題がこれです。set_target・build_project・flash_project を MCP 経由で呼ぶと、内部の処理は成功しているのに、MCP のタスクがいつまでも「実行中」のままになり、完了応答がクライアントに返ってきません。

• 再現性 — クリーンな環境を含めて 4/4 回再現しました。使う AI モデルを変えても同じだったため、クライアント側ではなくサーバ側の挙動と考えられます
• 2つの出方 — (a) 実処理は最後まで走るのに応答だけ返らない／(b) そもそも実処理が始まらずハングする（flash_project の初回。停止して再試行すると、2回目は約2秒で完走しました）
• 観測 — ビルドが set_target のタスクの中で走るなど、処理が遅れて実行されているように見える場面がありました

現実解：いまは eim run でシェルに直行する

完了応答の問題があるあいだ、実務でいちばん確実だったのは、MCP を介さずに eim run で idf.py を直接実行するやり方でした。

eim run "idf.py -C <プロジェクトのパス> set-target esp32s3"
eim run "idf.py -C <プロジェクトのパス> build"
eim run "idf.py -C <プロジェクトのパス> flash"

set-target → build → flash まで一気通貫で安定して通ります。この一連を Claude Code のスキルにまとめて自然言語から安定して回す方法は、続編の Claude Code スキルで ESP32 開発を自動化｜idf.py を直接叩く に、失敗込みの実戦テストとともにまとめました。ただし、この方法にも気をつける点が2つあります。

なお、この完了応答の問題は Espressif 側で解消され得る性質のものと見られます。現時点（2026-07-30）では未報告ですが、上流に共有する価値のある挙動です。

✅ まとめ

• ESP-IDF 6.0 は idf.py に MCP サーバを内蔵。Claude Code などから、自然言語で set_target → build_project → flash_project まで呼び出せます
• 接続は EIM で mcp 機能を有効化 → idf.py mcp-server を起動 → クライアントに登録の流れ。Claude Code なら claude mcp add --transport stdio ... の1行です
• 実機（Windows 11／ESP-IDF v6.0.2／ESP32-S3）では、接続・ツール一覧・実機書き込みまで成立を確認（2026-07-30）。導入では、eim install（引数なし）が mcp を入れないことと、mcp 2.0 が入ると起動できないこと（mcp[cli]<2 で回避）が要注意です
• ただし現状、重いツール呼び出しは「処理は成功するのに完了応答が返らない」（4/4 再現）。当面の現実解は eim run でのシェル直行です
• ドキュメント MCP サーバ（https://mcp.espressif.com/docs）を併用すると、AI が公式ドキュメントを根拠に動けます（こちらは今回未検証）
• できるのは操作の自動化まで。設計判断や原因究明は、これまでどおり自分の仕事です

関連記事

• Claude Code スキルで ESP32 開発を自動化｜idf.py を直接叩く：本記事の続編。MCP が完了応答を返さないときの現実解として、スキルで idf.py を直接叩く方法を実機検証しました
• VS Codeで始めるESP-IDF環境構築ガイド｜最小構成でHello Worldまで：ESP-IDF 環境構築の基本。MCP サーバもこの環境の上で動きます
• ESP32 シリーズの選び方｜S3・C3・C6・H2・P4 の違いと使い分け：set_target で指定するチップを、用途から選ぶためのガイド
• ESP32-S3 × ESP-IDF｜cJSONとHTTP ClientでJSONをPOST送信：MCP サーバでビルド・書き込みした先で、実際にデータを送る実装例

参考

• ESP-IDF Tools Local MCP Server（Espressif Developer Portal・2026年4月）
• Espressif Documentation MCP Server（Espressif Developer Portal・2026年4月）
• Espressif MCP Servers（公式ハブ）
• Announcing ESP-IDF v6.0（Espressif Developer Portal）
• The 2026-07-28 MCP Specification Release Candidate（Model Context Protocol Blog）