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このツールを使用するには、ターゲットデバイスに MicroPython ファームウェアを本体に書き込む必要があります。 詳細は MicroPython 公式サイト を参照してください。
ESP32 シリーズは esptool.py を利用してコマンドラインからインストールできます。
esptoolをインストール:pip install esptool
- 既存フラッシュの消去:
esptool.py --chip esp32 --port COMx erase_flash
- 新しいファームウェアの書き込み:
(※ チップの種類 (esp32, esp32s3, etc.) や構成により、書き込みアドレスが
esptool.py --chip esp32 --port COMx --baud 460800 write_flash -z 0x1000 <firmware_file>.bin
0x0になる場合があります。詳細は各ダウンロードページの指示に従ってください)
claude_desktop_config_example.json を参考に、各クライアントの設定ファイルに追記してください。
{
"mcpServers": {
"micropython": {
"command": "uv",
"args": [
"--directory",
"C:\\mcp-micropython-bridge",
"run",
"mcp-micropython-bridge"
]
}
}
}| リソース | 説明 |
|---|---|
micropython://guide/recipes |
よくある作業の進め方 |
micropython://policy/hardware-docs |
HARDWARE.md を更新すべき条件 |
micropython://guide/troubleshooting |
よくある問題の復旧手順 |
micropython://guide/limitations |
既知の制約一覧 |
| ツール | 説明 |
|---|---|
micropython_list_ports |
利用可能なシリアルポートを列挙 |
micropython_connect |
COM3 または host[:port] に接続 |
micropython_disconnect |
接続を切断 |
micropython_connection_status |
現在の接続状態を取得 |
micropython_exec |
Python コードをブロック実行 |
micropython_eval |
式を評価して値を返す |
micropython_get_info |
デバイス情報取得 |
micropython_reset |
ソフトリセット |
micropython_interrupt |
Ctrl-C を送って実行中の処理を中断 |
micropython_read_stream |
一定時間ぶんの出力を読む |
micropython_read_until |
特定文字列が出るまで待つ |
micropython_reset_and_capture |
ボードをリセットして起動ログを取得（serial 専用） |
micropython_list_files |
ファイル一覧 |
micropython_read_file |
ファイル読み出し |
micropython_read_hardware_md |
/HARDWARE.md を読み出し |
micropython_write_file |
ファイル書き込み |
micropython_append_file |
ファイル追記 |
micropython_delete_file |
ファイル削除 |
micropython_exec(timeout=...) の timeout は、コード送信開始から Raw REPL への復帰完了までを含む全体予算として扱います。
micropython_read_file / micropython_read_hardware_md / micropython_write_file / micropython_append_file の timeout も同じ意味です。
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 接続を使う場合は、対象ボード側の 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.pyserial REPL 上で一度だけ実行する初期設定スクリプトです。入力した値を NVS へ保存します
setup.py で保存する WEBREPL_PASSWORD は MicroPython WebREPL の制約に合わせて 8 文字以下にしてください。
資格情報はファイルではなく NVS に保存されますが、デバイス実機に保持される点は同じなので、取り扱い注意です。
設定後の流れ:
- serial 接続で
device_root\boot.pyをデバイスの/boot.pyとして書き込む - serial 接続で
device_root\setup.pyをデバイスの/setup.pyとして書き込む - serial REPL で
import setupを実行し、Wi-Fi SSID / Wi-Fi パスワード / WebREPL パスワードを保存する - ボードを再起動する
- Wi-Fi 側で割り当てられた IP アドレスを確認し、接続する
