warusakudeveroper/Arduino-MCP

MCP Arduino ESP32

Model Context Protocol (MCP) stdio server that automates ESP32 (Arduino core) development workflows on macOS, Linux, and Windows. It wraps arduino-cli for compile/upload, and uses Python pyserial for robust serial monitoring with auto-baud detection—enabling agents (Cursor, ClaudeCode CLI, Codex CLI, etc.) to operate ESP32 boards without the Arduino IDE.

🚀 クイックスタート

ESP32開発が初めての方は、quickstart ツールを使うだけで全て自動セットアップされます：

{ "name": "quickstart", "arguments": {} }

これだけで：

1. ✅ arduino-cli を自動インストール
2. ✅ Python + pyserial をセットアップ
3. ✅ ESP32 コアをインストール
4. ✅ 接続されたESP32を自動検出
5. ✅ Blinkサンプルをコンパイル＆アップロード
6. ✅ シリアル出力を確認

1. アーキテクチャ概要

1.1 MCP サーバー構成

1.2 対応プラットフォーム

1.3 Python 実行の選択順

1. 環境変数 MCP_PYTHON（例: /usr/bin/python3）
2. プロジェクト直下 .venv/bin/python
3. システムの python3

pyserial が存在しない場合、ensure_dependencies で自動インストールされます。

1.4 ボーレート自動判定

1. 候補値 [現在値, 115200, 74880, 57600, 9600] を短時間プローブ。
2. 取得文字列をスコアリング（印字可能率・改行数・キーワード）。
3. 最良スコアを採用、DTR/RTS パルスでボードをリセット。
4. Python モニタスクリプトで本番監視（行単位通知 or base64 chunk）。

2. インストール & 依存関係

2.1 前提条件

arduino-cli、ESP32コア、pyserial は quickstart または ensure_dependencies で自動インストールされます。

2.2 npm パッケージ

npm install -g @warusakudeveroper/mcp-arduino-esp32

Local install も可: npm install @warusakudeveroper/mcp-arduino-esp32

2.3 環境変数

3. MCP ツール仕様

3.1 初心者向け

3.2 セットアップ

3.3 ビルド & アップロード

3.4 シリアル監視

3.5 ボード & ライブラリ

3.6 ピンユーティリティ

3.7 重要仕様

• すべてのツールは MCP CallToolResult として structuredContent / テキスト要約を返す。
• monitor_start が auto_baud: true の場合、候補ボーレートでのスコアリング後に選択した値を通知。
• シリアル通知イベント
  • event/serial … line, raw, lineNumber, baud など
  • event/serial_end … reason, elapsedSeconds, rebootDetected, lastLine
• 停止条件 stop_on は正規表現（コンパイル前に検証）。
• パーティション変更などのカスタマイズは build_props (例: build.partitions) で対応。

3.8 ESP32-DevKitC ピン仕様 (pin_spec)

pin_spec ツールは公式ドキュメントの概要に基づき、DevKitC の各 GPIO の機能を返します（主なフィールド例）。

3.9 ピン整合性チェック (pin_check)

• .ino/.cpp（必要に応じ .h）を走査し、pinMode / digitalWrite / analogRead / touchRead などを解析。
• 代表的な検出内容:
  • 入力専用ピン (IO34–IO39) に対する pinMode(..., OUTPUT) や digitalWrite() を Error として報告。
  • ブートストラップピン (IO0/2/4/5/12/15) を出力駆動している場合は Warning（起動モードへの影響を説明）。
  • ADC 非対応ピンでの analogRead()、タッチ非対応ピンでの touchRead()、DAC 非対応ピンの dacWrite() などを検出。
  • SPI フラッシュ専用ピン (GPIO6〜11) を使用していれば警告。
  • マクロ等で解析できなかった識別子は unknownIdentifiers として列挙。

戻り値は ok（致命的エラー有無）、warnings[]（severity=error/warning/info）、usage[]（各ピンの使用状況）、unknownIdentifiers[] を含む JSON。エージェントが機能整合性を判断しやすい構造です。

4. MCP クライアント設定例

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "mcp-arduino-esp32": {
      "command": "mcp-arduino-esp32",
      "env": {
        "PATH": "/opt/homebrew/bin:${PATH}"
      }
    }
  }
}

ClaudeCode / Codex CLI (.mcp.json)

{
  "mcpServers": {
    "mcp-arduino-esp32": { "command": "mcp-arduino-esp32" }
  }
}

Windows 設定例

{
  "mcpServers": {
    "mcp-arduino-esp32": {
      "command": "mcp-arduino-esp32",
      "env": {
        "PATH": "C:\\Program Files\\nodejs;%PATH%"
      }
    }
  }
}

※ PATH に arduino-cli が含まれるよう設定（ensure_dependencies で vendor/ に自動配置も可）。

より詳しい設定例（ClaudeCode CLI / Codex CLI / Gemini CLI / Cursor）とシリアルコンソール利用手順は docs/cli-setup.md を参照してください。

5. 典型ワークフロー

5.1 初心者向け（推奨）

{ "name": "quickstart", "arguments": {} }

これだけで依存関係のセットアップからシリアル確認まで全て完了します。

5.2 手動ワークフロー

1. 依存関係セットアップ

   { "name": "ensure_dependencies", "arguments": { "install_missing": true } }
   

2. コンパイル

   {
     "name": "compile",
     "arguments": {
       "sketch_path": "~/Arduino/my-sketch",
       "export_bin": true
     }
   }
   

3. アップロード

   {
     "name": "upload",
     "arguments": {
       "sketch_path": "~/Arduino/my-sketch",
       "port": "/dev/cu.usbserial-0001"
     }
   }
   

4. シリアル監視

   {
     "name": "monitor_start",
     "arguments": {
       "port": "/dev/cu.usbserial-0001",
       "auto_baud": true,
       "max_seconds": 60
     }
   }
   

5.3 複数ESP32への一括フラッシュ

{
  "name": "flash_connected",
  "arguments": {
    "sketch_path": "~/Arduino/my-sketch",
    "max_ports": 10
  }
}

6. パーティション変更例

compile の build_props を利用:

{
  "name": "compile",
  "arguments": {
    "sketch_path": "~/Arduino/myapp",
    "build_path": "~/Arduino/myapp/.build",
    "build_props": {
      "build.partitions": "huge_app",
      "upload.maximum_size": "3145728"
    }
  }
}

カスタム CSV を用意する場合は、ESP32 コアに boards.txt を追加／上書きして build.partitions を参照させる。

7. シリアルログ例

ets Jul 29 2019 12:21:46
ESP32 Blink Example Starting...
If you see this message, serial communication is working!
LED initialized on GPIO 2
LED ON
LED OFF
LED ON

8. よくある質問

• パーティションの編集は可能？ 直接エディタは無いが、--build-property build.partitions=xxx などでボードオプションを指定できる。カスタム CSV を用いる場合は Arduino core の設定を変更。
• デバイス検出は？ arduino-cli board list --format json をラップした board_list で取得可能。
• モニタがバイナリノイズになる: auto_baud を有効にし、pyserial + DTR/RTS リセットが効くか確認。MCP_PYTHON で pyserial の入った Python を指定する。
• Windows で動かない: PowerShell が利用可能であることを確認してください。ensure_dependencies は PowerShell を使って arduino-cli をダウンロード・展開します。

9. 開発・テスト

npm install
npm run build
npm run lint

依存関係は quickstart または ensure_dependencies ツールで自動セットアップされます。

10. ドキュメント

11. ライセンス

MIT