Skip to main content
Glama
Sign In
mcp-micropython-bridge

mcp-micropython-bridge

by SWITCHSCIENCE
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: serial-mcp

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

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

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

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://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_stat_path

パス情報取得

micropython_read_file

ファイル読み出し

micropython_read_lines

行単位で一部読み出し

micropython_head_lines

先頭数行を読み出し

micropython_tail_lines

末尾数行を読み出し

micropython_read_hardware_md

/HARDWARE.md を読み出し

micropython_upload_file

ローカルファイルをデバイスへ転送

micropython_download_file

デバイスファイルをローカルへ保存

micropython_hash_file

デバイスファイルの SHA-256 を取得

micropython_compare_local_remote

ローカルとデバイスの一致確認

micropython_write_file

ファイル書き込み

micropython_append_file

ファイル追記

micropython_delete_file

ファイル削除

micropython_make_dir

ディレクトリ作成

micropython_remove_dir

空ディレクトリ削除

micropython_rename_path

パス名変更

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 アドレスを確認し、接続する

Available Tools

29 tools
micropython_append_fileB

MicroPython ボードのファイルに内容を追記する。

Args: path: 追記先ファイルのパス (例: "/main.py") content: 追記するテキスト内容。content_base64 とは排他的 timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 encoding: content をバイト列に変換するエンコーディング content_base64: base64 で表した追記データ。content とは排他的

Returns: ok: 追記に成功したら True path: 追記先パス bytes_written: 今回追記したバイト数 error: エラー時のメッセージ

Notes: content と content_base64 はどちらか片方のみ指定する。

Inputs: path (required), content, timeout, encoding, +1 more. Returns: ok, path, error, bytes_written

micropython_compare_local_remoteA

ローカルファイルとデバイス上のファイルが一致するか確認する。

Args: local_path: ホスト側ファイルパス。ワークスペース内のみ指定可能 remote_path: デバイス側ファイルパス timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数

Returns: ok: 比較処理に成功したら True local_path: 比較したローカルパス remote_path: 比較したデバイス側パス local_sha256: ローカルファイルの sha256 remote_sha256: デバイス側ファイルの sha256 same: 両者が一致したら True error: エラー時のメッセージ

Notes: 比較は sha256 ハッシュで行う。

Inputs: local_path (required), remote_path (required), timeout. Returns: ok, same, error, local_path, +3 more

micropython_connectB

指定ターゲットへ接続

Args: target: COM3 なら serial、host[:port] なら WebREPL password: WebREPL 接続時のパスワード baudrate: serial 接続時のボーレート

Inputs: target (required), baudrate, password. Returns: ok, host, port, error, +3 more

micropython_connection_statusA

現在の接続状態を返す

Returns: ok: 成功 True connected: 接続中なら True transport: serial または webrepl target: 接続時に指定したターゲット host: WebREPL 接続時のホスト port: 接続先ポート baudrate: serial 接続時のボーレート error: エラー時のメッセージ

Inputs: no named parameters. Returns: ok, host, port, error, +4 more

micropython_delete_fileB

MicroPython ボード上のファイルを削除する。

Args: path: 削除するファイルのパス (例: "/test.py")

Inputs: path (required). Returns: ok, path, error

micropython_disconnectA

現在の MicroPython ボード接続を切断 未接続時も成功を返す

Returns: ok: 成功 True error: エラー時のメッセージ

Inputs: no named parameters. Returns: ok, error

micropython_download_fileA

MicroPython ボード上のファイルをローカルへ保存する。

Args: remote_path: デバイス側ファイルパス local_path: ホスト側保存先パス。ワークスペース内のみ指定可能 timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 overwrite: False のとき既存ファイルを上書きしない

Returns: ok: 保存に成功したら True remote_path: 読み出したデバイス側パス local_path: 保存したローカルパス bytes_written: 保存したバイト数 sha256: 保存内容の sha256。失敗時は None error: エラー時のメッセージ

Inputs: local_path (required), remote_path (required), timeout, overwrite. Returns: ok, error, sha256, local_path, +2 more

micropython_evalB

MicroPython ボードで式を評価し、結果を文字列で返す。

Args: expression: 評価する Python 式 (例: "1 + 1", "machine.freq()")

Returns: ok: 評価に成功したら True result: 評価結果の文字列表現 error: エラー時のメッセージ。成功時は None

Inputs: expression (required). Returns: ok, error, result

micropython_execB

MicroPython インタープリタで Python コードを実行する。 複数行のコードも実行できる。

Args: code: 実行する Python コード (複数行可) timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 (デフォルト 10秒)

Returns: ok: 実行に成功したら True stdout: 標準出力 stderr: 標準エラー出力 error: エラー時のメッセージ。成功時は None

Example: code = "import machine\nprint(machine.freq())"

Inputs: code (required), timeout. Returns: ok, error, stderr, stdout

micropython_get_infoB

MicroPython ボードのデバイス情報を取得

Returns: ok: 成功 True info: 取得したデバイス情報 error: エラー時のメッセージ

Notes: info には必要に応じて次を含む。 platform, version, implementation, free_mem, alloc_mem, freq_mhz, fs_total_kb, fs_free_kb

Inputs: no named parameters. Returns: ok, info, error

micropython_hash_fileA

MicroPython ボード上のファイルのハッシュを返す。

Args: path: 対象ファイルパス algorithm: ハッシュアルゴリズム。現状は sha256 のみ timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数

Inputs: path (required), timeout, algorithm. Returns: ok, path, error, digest, +2 more

micropython_head_linesB

MicroPython ボード上のテキストファイル先頭の数行を返す。

Args: path: 対象ファイルパス lines: 返却する最大行数 timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 encoding: テキストデコードに使うエンコーディング errors: テキストデコード時のエラー処理

Returns: ok: 読み出しに成功したら True path: 対象ファイルパス content: 返したテキスト line_count: 返した行数 truncated: 返せなかった残り行があるとき True error: エラー時のメッセージ

Inputs: path (required), lines, errors, timeout, +1 more. Returns: ok, path, error, content, +2 more

micropython_interruptB

Ctrl-C を送って実行中の処理を中断

Inputs: no named parameters. Returns: ok, error

micropython_list_filesB

MicroPython ボードのファイルシステム上のファイル/ディレクトリを一覧表示

Args: path: 一覧表示するディレクトリのパス (デフォルト: "/")

Inputs: path. Returns: ok, path, error, entries

micropython_list_portsB

接続可能なシリアルポートを一覧表示

Inputs: no named parameters. Returns: ok, error, ports

micropython_make_dirA

MicroPython ボード上にディレクトリを作成する。

Args: path: 作成するディレクトリパス parents: True のときは親ディレクトリも順に作成 exist_ok: True のときは既存ディレクトリを許容

Inputs: path (required), parents, exist_ok. Returns: ok, path, error, parents

micropython_read_fileB

MicroPython ボードのファイルを読み出して返す

Args: path: 読み出すファイルのパス (例: "/main.py") timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 encoding: テキストデコードに使うエンコーディング errors: テキストデコード時のエラー処理 as_base64: True のときは content を空にし、content_base64 に base64 を返す

Returns: ok: 読み出しに成功したら True path: 読み出したファイルパス content: テキスト内容。as_base64=True のときは空文字列 content_base64: base64 内容。as_base64=False のときは None size_bytes: 読み出したバイト数 error: エラー時のメッセージ

Inputs: path (required), errors, timeout, encoding, +1 more. Returns: ok, path, error, content, +2 more

micropython_read_hardware_mdB

デバイス上の /HARDWARE.md を読み出して返す

Args: timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数

Inputs: timeout. Returns: ok, path, error, content, +2 more

micropython_read_linesB

MicroPython ボード上のテキストファイルを行単位で一部読み出す。

Args: path: 対象ファイルパス start_line: 1 始まりの開始行番号 max_lines: 返却する最大行数 timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 encoding: テキストデコードに使うエンコーディング errors: テキストデコード時のエラー処理

Returns: ok: 読み出しに成功したら True path: 対象ファイルパス start_line: 実際に使った開始行番号 line_count: 返した行数 content: 返したテキスト eof: 返却範囲がファイル末尾に達したら True error: エラー時のメッセージ

Inputs: path (required), errors, timeout, encoding, +2 more. Returns: ok, eof, path, error, +3 more

micropython_read_streamA

接続中のデバイスから一定時間ストリーム出力を読み取る

Args: duration: 読み取りを続ける最大秒数 idle_timeout: この秒数だけ無通信なら早期終了 max_bytes: 読み取る最大バイト数。超えると truncated=True

Returns: ok: 成功 True stdout: 読み取ったテキスト truncated: max_bytes で打ち切られたら True bytes_read: 実際に読んだバイト数 error: エラー時のメッセージ

Inputs: duration (required), max_bytes, idle_timeout. Returns: ok, error, stdout, truncated, +1 more

micropython_read_untilB

接続中のデバイス出力を、指定文字列が現れるまで読み取る

Args: pattern: 検出したい文字列。正規表現ではなく部分文字列 timeout: 待機する最大秒数 max_bytes: 読み取る最大バイト数

Returns: ok: 成功 True matched: pattern を検出したら True stdout: 読み取ったテキスト bytes_read: 実際に読んだバイト数 error: エラー時のメッセージ

Inputs: pattern (required), timeout (required), max_bytes. Returns: ok, error, stdout, matched, +1 more

micropython_remove_dirC

MicroPython ボード上の空ディレクトリを削除する。

Args: path: 削除するディレクトリのパス

Inputs: path (required). Returns: ok, path, error

micropython_rename_pathB

MicroPython ボード上のパスを rename/move する。

Args: src: 移動元パス dst: 移動先パス

Inputs: dst (required), src (required). Returns: ok, dst, src, error

micropython_resetA

MicroPython ボードをソフトリセット (machine.reset() に相当) リセット後は再接続が必要

Inputs: no named parameters. Returns: ok, error

micropython_reset_and_captureA

デバイスをリセットし、起動直後の出力を一定時間読み取る

Args: capture_duration: リセット後の読み取り最大秒数 idle_timeout: この秒数だけ無通信なら早期終了 max_bytes: 読み取る最大バイト数。超えると truncated=True

Returns: ok: リセットと読み取り呼び出しに成功したら True stdout: 起動後に取得したテキスト reset_ok: リセット操作自体が成功したら True truncated: max_bytes で打ち切られたら True error: エラー時のメッセージ

Inputs: capture_duration (required), max_bytes, idle_timeout. Returns: ok, error, stdout, reset_ok, +1 more

micropython_stat_pathC

MicroPython ボード上のパス情報を取得

Args: path: 対象パス

Returns: ok: 取得に成功したら True path: 対象パス kind: file, dir, unknown のいずれか size_bytes: ファイルサイズ mode: os.stat() の mode 値 mtime: 更新時刻 error: エラー時のメッセージ

Inputs: path (required). Returns: ok, kind, mode, path, +3 more

micropython_tail_linesB

MicroPython ボード上のテキストファイル末尾の数行を返す。

Args: path: 対象ファイルパス lines: 返却する最大行数 timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 encoding: テキストデコードに使うエンコーディング errors: テキストデコード時のエラー処理

Returns: ok: 読み出しに成功したら True path: 対象ファイルパス content: 返したテキスト line_count: 返した行数 truncated: 返せなかった先頭側の行があるとき True error: エラー時のメッセージ

Inputs: path (required), lines, errors, timeout, +1 more. Returns: ok, path, error, content, +2 more

micropython_upload_fileB

ローカルファイルを MicroPython ボードへ転送

Args: local_path: ホスト側ファイルパス。ワークスペース内のみ指定可能 remote_path: デバイス側ファイルパス timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 overwrite: False のとき既存ファイルを上書きしない

Returns: ok: 転送に成功したら True local_path: 読み込んだローカルパス remote_path: 書き込んだデバイス側パス bytes_written: 書き込んだバイト数 sha256: 転送内容の sha256。失敗時は None error: エラー時のメッセージ

Inputs: local_path (required), remote_path (required), timeout, overwrite. Returns: ok, error, sha256, local_path, +2 more

micropython_write_fileA

MicroPython ボードのファイルに内容を書き込む（上書き）。

Args: path: 書き込み先ファイルのパス (例: "/main.py") content: 書き込むテキスト内容。content_base64 とは排他的 timeout: コード送信から Raw REPL 復帰完了までの全体タイムアウト秒数 encoding: content をバイト列に変換するエンコーディング content_base64: base64 で表した書き込みデータ。content とは排他的

Returns: ok: 書き込みに成功したら True path: 書き込み先パス bytes_written: 書き込んだバイト数 error: エラー時のメッセージ

Notes: content と content_base64 はどちらか片方のみ指定する。

Inputs: path (required), content, timeout, encoding, +1 more. Returns: ok, path, error, bytes_written

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target a distinct resource and action, with clear separation between file reads, uploads, downloads, stream reads, and directory operations. A few pairs such as eval vs exec and read_file vs download_file require reading descriptions, but boundaries are still understandable.

    Naming Consistency5/5

    All tools use the same micropython_ prefix and snake_case verb_noun style, making the set predictable and easy to scan.

    Tool Count3/5

    29 tools is heavy for this server, and several convenience operations around file reading and streaming could likely be consolidated. The breadth is justifiable for a MicroPython bridge, but the count sits at the borderline of being excessive.

    Completeness4/5

    The surface covers connection lifecycle, execution, reset/interrupt, file CRUD, directory operations, transfers, hashing/comparison, and stream reading. Minor gaps such as recursive directory deletion or on-device copy remain, but core workflows are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers