mcp-micropython-bridge

MicroPython REPL への MCP ブリッジサーバー。

Claude Desktop, Codex (VSCode), Copilot (VSCode), Antigravity などの MCP クライアントから、 USB Serial または WebREPL 経由で MicroPython (ESP32, RP2040, etc.) を操作できます。

HARDWARE.md を単なる配線メモではなく、将来のセッションが再利用するためのボード固有ドキュメントとして育てていく運用を想定しています。たとえばサーボ操作の依頼が来たら、その場限りのコード片で済ませるのではなく、小さな helper module をデバイス上に作成し、今後の使い方や前提が増えたときだけ HARDWARE.md に短い利用メモを追記して、次回以降はその helper を再利用する形を推奨します。

セットアップ

# 依存関係のインストール
uv sync

# サーバー起動（動作確認用）
uv run mcp-micropython-bridge

# tools ラッパー経由の実機テスト CLI
uv run python -m mcp_micropython.device_test_cli --target COM3

Related MCP server: emcp

MicroPython ファームウェアの書き込み

このツールを使用するには、ターゲットデバイスに MicroPython ファームウェアを本体に書き込む必要があります。 詳細は MicroPython 公式サイト を参照してください。

ターゲット別ダウンロードページ

• ESP32

• ESP32-S3

• ESP32-C5

• RP2040

• RP2350

ESP32 へのインストール例 (esptool.py)

ESP32 シリーズは esptool.py を利用してコマンドラインからインストールできます。

1. esptool をインストール:

   pip install esptool

2. 既存フラッシュの消去:

   esptool.py --chip esp32 --port COMx erase_flash

3. 新しいファームウェアの書き込み:

   esptool.py --chip esp32 --port COMx --baud 460800 write_flash -z 0x1000 <firmware_file>.bin

   (※ チップの種類 (esp32, esp32s3, etc.) や構成により、書き込みアドレスが 0x0 になる場合があります。詳細は各ダウンロードページの指示に従ってください)

MCP クライアントへの登録

claude_desktop_config_example.json を参考に、各クライアントの設定ファイルに追記してください。

{
  "mcpServers": {
    "micropython": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\mcp-micropython-bridge",
        "run",
        "mcp-micropython-bridge"
      ]
    }
  }
}

提供リソース

提供ツール

micropython_exec(timeout=...) の timeout は、コード送信開始から Raw REPL への復帰完了までを含む全体予算として扱います。 micropython_read_file / micropython_read_hardware_md / micropython_write_file / micropython_append_file の timeout も同じ意味です。

micropython_write_file は content によるテキスト書き込みと content_base64 によるバイナリ書き込みをサポートします。 micropython_append_file も同じ入出力形式で末尾追記できます。 micropython_read_file(as_base64=True) を使うと、改行コードや非 UTF-8 バイト列を保持したまま取得できます。

実機テスト CLI

src/mcp_micropython/tools の登録済みツール関数を FakeMCP 経由で呼び出し、実機に対して接続確認やファイル I/O、serial 専用の stream/reset 系チェックをまとめて実行できます。

# Serial で拡張セットを実行
uv run python -m mcp_micropython.device_test_cli --target COM3

# WebREPL で共通テストだけ実行
uv run python -m mcp_micropython.device_test_cli --target 192.168.1.10:8266 --password secret --tests common,filesystem

# エントリーポイントから起動
uv run mcp-micropython-device-test --target COM3 --tests all

主なオプション:

• --target: COM3 または host[:port]

• --password: WebREPL 用パスワード

• --baudrate: serial ボーレート

• --tests: all, common, filesystem, serial, stream, reset

• --large-file-size: 長文転送テストのサイズ

• --exec-timeout: exec / ファイル操作タイムアウト

• --read-timeout: read_until / read_stream / reset_and_capture の待機時間

• --reconnect-timeout: serial リセット後に COM ポートが再出現するまで待つ時間

serial で stream / reset を実行する場合、一時的に /main.py を差し替えて起動ログを検証したあと、元の内容へ復元します。/boot.py は変更しませんが、変更前提の確認として読み出します。

WebREPL 事前設定

WebREPL 接続を使う場合は、対象ボード側の Wi-Fi 接続と webrepl.start() が事前設定済みである必要があります。 この MCP サーバーは設定済みの WebREPL へ接続することだけを担当し、boot.py への初期セットアップは行いません。

このリポジトリには、初期設定用ファイルとして device_root\boot.py と device_root\setup.py を同梱しています。

• device_root\boot.py デバイス起動時に NVS から Wi-Fi SSID / Wi-Fi パスワード / WebREPL パスワードを読み出し、Wi-Fi 接続と webrepl.start() を実行します

• device_root\setup.py serial REPL 上で一度だけ実行する初期設定スクリプトです。入力した値を NVS へ保存します

setup.py で保存する WEBREPL_PASSWORD は MicroPython WebREPL の制約に合わせて 8 文字以下にしてください。 資格情報はファイルではなく NVS に保存されますが、デバイス実機に保持される点は同じなので、取り扱い注意です。

設定後の流れ:

1. serial 接続で device_root\boot.py をデバイスの /boot.py として書き込む

2. serial 接続で device_root\setup.py をデバイスの /setup.py として書き込む

3. serial REPL で import setup を実行し、Wi-Fi SSID / Wi-Fi パスワード / WebREPL パスワードを保存する

4. ボードを再起動する

5. Wi-Fi 側で割り当てられた IP アドレスを確認し、接続する