Arduino MCP Server

arduino-mcp-server

AI アシスタントから Arduino を完全に操作できます。コンパイル、アップロード、シリアルモニタリング、配線の安全性確認まで、すべて自然言語で実行できます。

HardwareMCP エコシステムの一部です。AI と物理ハードウェアをつなぐオープンソースの MCP サーバー群です。

---

できること

AI アシスタントは Jira、GitHub、データベースを操作できます。しかし、これまではマイクロコントローラーと通信できませんでした。

arduino-mcp-server は arduino-cli を MCP サーバーとしてラップし、AI から次の操作を可能にします。

• 接続されたボードとポートを自動検出します
• ターミナルを使わずにスケッチをコンパイルしてアップロードします
• 状態を保持するセッションでシリアル出力をモニタリングします（open、read、expect、write、close）
• ハードウェアにコマンドを送る前に電気的な安全性を確認します
• コア、ライブラリ、CLI のインストールなどの依存関係を管理します

---

クイックスタート

インストール：

npm install -g arduino-mcp-server

Claude Desktop に追加します（claude_desktop_config.json）：

{
  "mcpServers": {
    "arduino": {
      "command": "npx",
      "args": ["-y", "arduino-mcp-server"],
      "env": {
        "ARDUINO_CLI_PATH": "arduino-cli",
        "ARDUINO_SKETCH_ROOT": "/path/to/your/sketches"
      }
    }
  }
}

arduino-cli が PATH に必要です。または、サーバーにインストールさせることもできます。

---

できることの例

ゼロからセットアップする：

「Arduino CLI がインストールされているか確認して、Arduino Uno の環境をすべてセットアップしてください。」

コンパイルしてアップロードする：

「Blink スケッチをコンパイルして、COM6 に接続されている Uno にアップロードしてください。」

シリアルモニタリング：

「COM6 で 115200 baud のシリアル通信を開き、デバイスが READY を出力するまで待ってください。」

安全性を優先するワークフロー：

「コマンドを送る前に、ピン 13 に 5V、25mA を出力する Arduino Uno の安全性を事前確認してください。」

---

ツール

ツール	説明
arduino_cli_doctor	Arduino CLI のインストールとバージョンを確認します
install_arduino_cli	arduino-cli のインストール手順を案内します
detect_hardware	接続されたボードを検出し、FQBN を推定します
list_connected_boards	接続されている Arduino ボードをすべて一覧表示します
list_serial_ports	使用可能なシリアルポートを一覧表示します
ensure_core_installed	ボードコアを確認・インストールします
compile_sketch	対象ボード用にスケッチをコンパイルします
upload_sketch	コンパイル済みスケッチをボードにアップロードします
upload_and_wait_ready	アップロードして、デバイスの準備完了信号を待ちます
serial_open_session	状態を保持するシリアルセッションを開きます
serial_read	バッファーに保存されたシリアルデータを読み取ります
serial_expect	シリアル出力にパターンが現れるまで待ちます
serial_write	シリアル経由でデータを送信します
serial_close_session	シリアルセッションを閉じます
serial_list_sessions	アクティブなシリアルセッションを一覧表示します
read_serial_snapshot	シリアルデータを一度だけすばやく読み取ります
safety_preflight	ハードウェア操作前に電気的な安全性を確認します
get_board_details	ボードのピンと機能の詳細を取得します
list_supported_boards	arduino-cli がサポートするすべてのボードを一覧表示します
list_board_reference	ボードのピンリファレンスを参照します
search_board_reference	キーワードでボードリファレンスを検索します

リソース：

• arduino://boards/reference — ボードのピンと機能をまとめた構造化リファレンス

プロンプト：

• arduino-cli-bootstrap-policy — arduino-cli のセットアップ動作に関するポリシー
• arduino-setup-assistant — Arduino 環境のセットアップをガイドします

---

安全性の事前チェックガードレール

safety_preflight（および upload_sketch、upload_and_wait_ready、serial_write に渡される safetyContext）では、バッテリーと ESP32 ファミリーのピンに関する注意点もチェックするようになりました。特定のボードに固定せず、小規模で拡張可能なデータテーブルを使用しています。

バッテリー充電レート（C レート）チェック — battery オブジェクト（capacityMah、chargeCurrentMa、chemistry）を渡すと、チェックで chargeCurrentMa / batteryCapacityMah を計算して、次のように警告します。

• BATTERY_CRATE_UNSAFE（重大、ブロック）：1C 超
• BATTERY_CRATE_CAUTION（軽度、ブロックなし）：0.5C 超

一般的な小型 LiPo セルの安全な充電電流は、通常およそ 0.5～1C とされています。そのため、メッセージには計算式が明記されます。例：「100mAh のセルに 380mA を流すと 3.8C のレートになります。一般的な小型 LiPo セルの安全範囲である約 0.5～1C を大きく上回るため、続行する前にセルの実際の定格充電電流を確認してください。」 chargeCurrentMa が省略された場合は、小型ボードからオンボード充電 IC を引くルックアップテーブルを使って推定します（現在は Seeed XIAO ESP32S3、XIAO ESP32S3 Sense、XIAO ESP32C3 を登録済みです。data/battery-charge-ic-reference.json を参照してください。ボードは簡単に追加できます）。これらはメーカーが公開しているおおよその値です。本番ワークフローで信頼する前に、使用するボードのリビジョンに対応する最新のデータシートや Wiki で確認してください。

バッテリー極性の確認 — battery.connecting: true の場合（またはバッテリーのフィールドが設定されている場合）に、battery.polarityConfirmed が明示的に true でなければ、事前チェックで BATTERY_POLARITY_UNCONFIRMED によりブロックし、配線の色から BAT+/BAT- を決して推測しないよう注意を促します。Seeed XIAO ボードでは、公式の規則として、USB-C ポートに近い側がマイナス、遠い側がプラスであることを示します。

ESP32 ファミリーのピン安全性（data/board-reference.json によるボードごとのテーブル駆動）：

• SPI フラッシュピン（クラシック ESP32 WROOM/WROVER モジュールの GPIO6-11）— 重大なエラー（SPI_FLASH_PIN_USED）。これらに配線すると起動できなくなります。
• ブートストラップピン（クラシック ESP32 の GPIO0/2/12/15）— 注意が必要です。実行時には使用できますが、起動／リセット時に外部から状態を固定するとリスクがあります（既存のチェック）。
• 内部プル抵抗のない入力専用ピン（クラシック ESP32 の GPIO34-39）— 注意が必要です（NO_INTERNAL_PULL_PIN）。ボタン／スイッチに使用する場合は、外部プルアップ／プルダウン抵抗を追加してください。
• Seeed XIAO ESP32S3 — 使用可能な GPIO 11 本（D0-D10）、デフォルトの I2C（D4/D5）をモデル化しています。また、D6/D7 に配線されている場合は情報メッセージを表示します。これらはデフォルトでハードウェア UART1 の TX/RX ですが、「USB CDC on Boot」を有効にすると通常の GPIO として使用できます。

上記すべてのボードデータは JSON に保存され、ボード ID／FQBN をキーとして管理されます。そのため、ガードレールのロジックを変更せずにボードを追加できます。

---

設定

変数	デフォルト	説明
ARDUINO_CLI_PATH	arduino-cli	arduino-cli バイナリへのパス
ARDUINO_SKETCH_ROOT	(なし)	スケッチのパスをこのディレクトリに制限します

---

開発

git clone https://github.com/hardware-mcp/arduino-mcp-server
cd arduino-mcp-server
npm install
npm run typecheck
npm test
npm run build
npm run dev

---

HardwareMCP の一部

このサーバーは HardwareMCP エコシステムの一部です。AI アシスタントが物理ハードウェアを実際に操作できるようにする MCP サーバーのコレクションです。

---

ライセンス

MIT — LICENSE を参照してください。

サポート

Issue を作成