Robot NXT Control MCP

Windows 11 に USB/WinUSB で接続された互換プログラマブルブリック・ハードウェア向けのローカル MCP サーバー。

互換性と商標

この独立したプロジェクトは、LEGO Group とは提携・スポンサー関係になく、LEGO Group の承認も受けていません。LEGO、MINDSTORMS、NXT は LEGO Group の商標です。これらは、互換ハードウェア、ソフトウェア、プロトコル、およびサードパーティ依存関係を識別するためにのみ本書で使用されており、このプロジェクトの名前、サーバー識別子、またはプラグイン識別子の一部ではありません。

以前のリリースからの移行

旧プラグインおよび MCP サーバー識別子は robot-nxt-control に置き換えられ、実行可能ファイルは robot-nxt-control-mcp、robot-nxt-control-mcp-stdio、robot-nxt-control-mcp-http と改名されました。この変更を取り込んだ後、編集可能なパッケージを再インストールし、以前の MCP 設定エントリを以下の例に置き換えてください。

Related MCP server: KentraBOT MCP Server

Claude Desktop または Codex desktop（Windows）へのインストール

最初にWindows のインストールを完了してください。これらのデスクトップアプリは MCP サーバーを自ら起動するため、robot-nxt-control-mcp-stdio.exe を手動で実行しないでください。以下の例では、このリポジトリが C:\Users\lukas\workspace\NXT-MCP にあることを前提としています。チェックアウト先が別の場所にある場合は、すべてのパスのその部分を置き換えてください。

Claude Desktop

1. Claude Desktop を完全に終了します（トレイアイコンも含む）。

2. %APPDATA%\Claude\claude_desktop_config.json を開きます。ファイルが存在しない場合は作成します。すでに mcpServers オブジェクトがある場合は、以下の robot-nxt-control エントリのみを追加します。

3. ファイルを保存し、Claude Desktop を再起動します。サーバーが Settings → Developer → MCP servers に表示されるはずです。

{
  "mcpServers": {
    "robot-nxt-control": {
      "command": "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe",
      "cwd": "C:\\Users\\lukas\\workspace\\NXT-MCP"
    }
  }
}

同じコピー＆ペースト用の設定は packaging/claude-desktop/mcp.json にあります。

Codex desktop

Codex desktop ホストと Codex CLI は、%USERPROFILE%\.codex\config.toml の共有 MCP 設定を使用します。以下のブロックを追加するか（または同等の codex mcp add コマンドを実行）、Codex アプリを再起動してください:

[mcp_servers.robot-nxt-control]
command = "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe"
cwd = "C:\\Users\\lukas\\workspace\\NXT-MCP"
startup_timeout_sec = 10
tool_timeout_sec = 120

PowerShell での代替方法:

codex mcp add robot-nxt-control -- C:\Users\lukas\workspace\NXT-MCP\.venv\Scripts\robot-nxt-control-mcp-stdio.exe
codex mcp list

ChatGPT desktop MCP UI の場合: Settings → MCP servers → Add server で STDIO を選択し、robot-nxt-control と入力し、コマンドとして同じ実行可能ファイルを使用して保存し、アプリを再起動します。ローカルの Codex クライアントは STDIO と Streamable HTTP の両方をサポートし、この MCP 設定を共有します。OpenAI 公式 MCP ドキュメント

最初の確認

新しいチャットを開き、nxt_info を要求してください。接続できない場合は、まず ./.venv/Scripts/nxt-test.exe --log-level=debug でロボットが動作することを確認し、次に設定されたすべてのパスが存在し、NXT の電源が入っていることを確認してください。移動ツールは実際のハードウェアを制御します: 最初に nxt_info または query_all_state を使用し、その後は低出力で移動範囲を制限したコマンドを使用してください。

MCP トランスポート、ホスト、および検証

同じ create_server() ファクトリが両方のトランスポートを駆動します。robot-nxt-control-mcp-stdio は、Claude Desktop、Claude Code、Codex CLI、Codex desktop、およびローカルの Codex プラグイン向けのローカルプロセストランスポートです。プロトコルトラフィックは stdout にのみ書き込みます。

提供された JSON を開始設定として使用し、チェックアウトを移動した後、絶対ワークスペースパスを置き換えてください:

• Claude Desktop: packaging/claude-desktop/mcp.json

• Claude Code プラグイン: packaging/claude-code/

• Codex ローカルプラグイン: C:\Users\lukas\plugins\robot-nxt-control（パーソナルマーケットプレイスで作成）

プロトコルテスト用に、ループバック上で Streamable HTTP を起動します:

.\.venv\Scripts\robot-nxt-control-mcp-http.exe --port 8000
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list
npx @modelcontextprotocol/conformance server --url http://127.0.0.1:8000/mcp --suite active

.\.venv\Scripts\python.exe -m pytest でリポジトリチェックを実行します。これには、コントローラおよびビヘイビアテストに加えて、インプロセス MCP ネゴシエーション、tools/list、アノテーション、tools/call テストが含まれます。conformance-baseline.yml には、この特化型ハードウェアサーバーがアドバタイズしないオプションの MCP 機能を必要とする汎用シナリオのみが記録されています。各エントリはバーンダウンアサーションであるため、ランナーは古いエントリをフラグ付けします。

robot-nxt-control-mcp-http はデフォルトで 127.0.0.1 にバインドされ、NXT_MCP_ALLOW_REMOTE=true が明示的に設定されていない限り、ループバック以外のバインドを拒否します。クラウドクライアントは USB NXT に直接到達できません: このサーバーをロボットの隣で実行し、OAuth/トークン検証、認可、監査ログ、ネットワーク制限を備えた本番 HTTPS リバースプロキシを Streamable HTTP エンドポイントの前に配置してください。環境変数のオーバーライドのみで USB 制御エンドポイントを公開しないでください。

モジュール設計、MCP およびビヘイビア実行フロー、USB スタック、安全モデル、Mermaid 図については ARCHITECTURE.md を参照してください。

Windows 11 のインストール

Python 3.11 x64 を使用してください。PowerShell から:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[test]"

1. Zadig で NXT デバイスドライバをインストール

NXT の電源を入れ、USB で接続します。PowerShell で、Windows が通常モードのデバイスを認識していることを確認します:

Get-PnpDevice -PresentOnly |
  Where-Object InstanceId -match 'VID_0694&PID_0002' |
  Format-List Status,FriendlyName,InstanceId,Problem

ハードウェア ID に USB\VID_0694&PID_0002 が含まれている必要があります。Problem が CM_PROB_FAILED_INSTALL であるか、デバイスマネージャーに Code 28 が表示される場合は、ドライバがありません。

1. Zadig は https://zadig.akeo.ie/ からのみダウンロードしてください。

2. Zadig を管理者として実行します。

3. Options > List All Devices を選択します。

4. USB ID が正確に 0694:0002 のエントリを選択します。表示されたデバイス名だけでなく、ID を使用してください。

5. ドライバセレクタで WinUSB を選択します。

6. Install Driver または Replace Driver をクリックします。

7. NXT の電源を入れたまま、USB を抜いて再接続します。

03EB:6124 を選択しないでください。これは NXT ブートローダー/ファームウェア更新モードです。無関係な USB デバイスのドライバを置き換えないでください。WinUSB をインストールすると、LEGO/Fantom ドライバが復元されるまで、古い LEGO NXT-G ソフトウェアがブリックと通信できなくなる可能性があります。

2. PyUSB 用の x64 libusb ランタイムをインストール

WinUSB は Windows デバイスドライバです。PyUSB は別途、ユーザースペースの libusb-1.0.dll を必要とします。リポジトリには、公式の libusb 1.0.30 アーカイブをダウンロードし、その SHA-256 を検証し、この環境の python.exe の隣に VS2022 x64 DLL をインストールするヘルパーが含まれています:

.\scripts\install-libusb-runtime.ps1

ヘルパーは PATH 上の 7z.exe を必要とします。手動でインストールするには、公式 libusb GitHub リリースから libusb-1.0.30.7z をダウンロードし、VS2022\MS64\dll\libusb-1.0.dll を抽出して、.venv\Scripts\libusb-1.0.dll にコピーしてください。64 ビット Python で MS32 DLL を使用しないでください。

ランタイムを独立して検証します:

$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
.\.venv\Scripts\python.exe -c "import usb.backend.libusb1 as b; assert b.get_backend() is not None; print('libusb OK')"

MCP サーバーは、仮想環境の Python の隣にインストールされた DLL を自動的に自身の検索パスに追加します。nxt-test.exe は外部の NXT-Python コマンドであるため、使用する前に上記の $env:PATH 行を実行するか、仮想環境をアクティブ化してください。

3. ブリックをテスト

MCP の前にハードウェアを検証します:

.\.venv\Scripts\nxt-test.exe --log-level=debug

テストが成功すると、ブリック名、バッテリーレベル、プロトコルバージョン、ファームウェアバージョンが表示されます。それでもブリックが見つからないと報告される場合は、デバイスマネージャーで 0694:0002 デバイスを再確認し、そのドライバが WinUSB であることを確認してください。

ファームウェア

NXT が正常に起動し、Windows が VID 0694 / PID 0002 を表示する場合、ファームウェアのインストールや更新は不要です。MCP サーバーは標準の NXT ダイレクトコマンドを使用し、nxt_info を通じてインストール済みのファームウェアとプロトコルバージョンも報告します。

ブリックが正常に起動できず、代わりに Windows が VID 03EB / PID 6124（Atmel SAM-BA ファームウェア更新モード）を表示する場合にのみ、ファームウェアリカバリを実行してください。リカバリはブリックのファームウェアを消去して書き換えるもので、通常の MCP セットアップの範囲外です:

1. 03EB:6124 に対して通常の NXT WinUSB ルールをインストールしないでください。

2. 元の LEGO MINDSTORMS NXT ソフトウェアが必要とするファームウェア更新ドライバを復元/使用します。

3. そのソフトウェアで、Tools > Update NXT Firmware を使用し、公式の NXT ファームウェアイメージを使用します。

4. リカバリ後、ブリックの電源を入れ直します。0694:0002 として戻る必要があります。その後、必要に応じて通常モードのデバイスに WinUSB を再度インストールします。

NXT-Python は意図的にファームウェアフラッシュを提供していません。NoBackendError、Code 28、または MCP 接続失敗のトラブルシューティングのために、ファームウェアブートモードを起動したり、更新を試みたりしないでください。

次に MCP Inspector を開きます:

.\.venv\Scripts\mcp.exe dev src\nxt_mcp\server.py

ローカル MCP ホストの場合、コマンド .venv\Scripts\robot-nxt-control-mcp.exe、作業ディレクトリをリポジトリとして stdio サーバーを設定します。

サーバーを起動する前にブリックに接続されているセンサーを宣言すると、ブリック全体のスナップショットが即座に型付きの読み取り値を返すことができます:

$env:NXT_SENSOR_MAP = "1:touch,2:light,4:ultrasonic"
.\.venv\Scripts\robot-nxt-control-mcp.exe

read_sensor またはセンサー駆動のモーターコマンドを呼び出すと、そのポートのタイプも後続のスナップショット用に記憶されます。

高レベルツール

• move_motor_relative(port="C", power=40, degrees=2000) は C を 2000 エンコーダー度だけ前方に移動します。逆方向には負の power を使用します。アダプターは、NXT-Python の標準 turn() ループが小さな移動にはポーリングが遅すぎるため、タイトな USB エンコーダーループを使用します。約 45 度の移動には、20 などの低い power を使用してください。

• zero_motor_position(port="C") は現在の C エンコーダー位置を絶対 0 として定義します。move_motor_absolute(port="C", target_degrees=-90, power=20) はその後 -90 に移動します。絶対移動はターゲットから方向を導出します。その power は正の大きさです。

• motor_position(port="C") は絶対/プログラム相対エンコーダー位置と生のタコカウンターを報告します。

• run_motor(port="C", power=-30) は、停止コマンドまたは制限付きビヘイビアが停止するまで、負の方向に連続して実行します。regulated=true の場合、power は NXT のレギュレーション速度設定であり、校正された度/秒の値ではありません。

• run_motors(ports=["B", "C"], powers=[30, -30]) は 1 回の MCP 呼び出しでモーターグループを開始します。stop_motors、move_motors_relative、move_motors_absolute も同様にグループに対して動作します。リストは位置対応です: 各 power/degree 値は同じインデックスのポートに属します。

• run_motor_until_sensor(port="B", power=40, sensor_port=1, sensor_type="touch", condition="pressed") はタッチ S1 が押されるまで B を実行します。

• run_motors_until_sensor(ports=["B", "C"], powers=[40, 40], sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20) は障害物が最大 20 cm になるまで両方のモーターを駆動し、その後グループ全体を停止します。

• run_motor_until_sensor(port="B", power=40, sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20) は障害物が最大 20 cm になるまで B を実行します。

• query_all_state(format="text") はブリック、すべてのモーターポート、すべてのセンサーポートの 1 つのコンパクトなテキストスナップショットを返します。構造化データには format="json" を使用してください。

• cycle_motor_on_touch(port="C", touch_port=1, cycles=5) は S1 が押されるまで前方に実行し、離されるまで反転し、5 回繰り返し、成功後にビープ音を鳴らします。各プレスおよびリリースフェーズには独自のタイムアウトとエンコーダー移動上限があります。

すべてのセンサー駆動のモーションにはタイムアウトとエンコーダー移動制限があります。どちらかの制限に達するとモーターが停止し、理由とともに ok: false が返されます。センサーまたは USB 読み取りが失敗した場合もモーターは停止します。

拡張診断、ストレージ、およびテレメトリ

• motor_state(port) は制御、実行状態、タコメータ、設定済み出力状態を報告します。 drive_sync(left_port, right_port, power, turn_ratio=0) は差動駆動ペアにNXTファームウェアの同期制御を使用します。wait_motors(...) には期限があり、タイムアウト時にポートを停止します。

• read_sensor_raw(port, sensor_type?)、wait_sensor(...)、sensor_stream(...) は制限付き診断、デバウンス処理されたセンサー待機、有限サンプルを提供します。

• 光、色、超音波センサーの場合は、zero_sensor_reference(port, sensor_type) を呼び出してから read_sensor_relative(port, sensor_type) を呼び出します。これは、キャプチャしたゼロからの変化量と絶対値を返します。色は意味のある減算のために反射光強度（離散的な赤/青などのラベルではなく）を使用します。

• log_start、log_status、log_stop、log_export は制限付きホスト側CSVテレメトリを提供します。有効なチャネルは battery_mv、motor:A から motor:C、sensor:1:touch（または他のサポートされているセンサータイプ/ポート）です。

• list_files、read_file、write_file、delete_file は制限付きNXTユーザーファイルを管理します。書き込みは .txt、.csv、.dat、.rso に制限されます。サウンド再生は play_sound_file(name) と stop_sound() を使用します。

• mailbox_send / mailbox_receive は最大58 UTF-8バイトのメッセージをサポートします。i2c_transaction は16バイトのリクエストとレスポンスペイロードに制限されたオプトインの低速操作です。set_brick_name と keep_alive はサポートされている管理用ダイレクトコマンドです。

標準のNXTダイレクトコマンドプロトコルは、NXT LCDに描画したり、そのボタンを読み取ったりすることはできません。これらのNXT-G/ROBOTC機能には、別途インストールするNXT常駐ブリッジプログラムが必要です。これらは意図的にこのサーバーでは公開されていません。

モーター位置決めのセマンティクス

NXTエンコーダーカウントはモーターシャフトの度数であり、ロボットの進行方向の度数や直線ミリメートルではありません。ギア比、ホイール円周、ホイールスリップは、物理単位が必要な場合はロボットのビヘイビアで処理する必要があります。

絶対ゼロはNXTファームウェアのプログラム相対回転カウンタによって保持されます。これはホーミングセンサーではなく、永続的でもありません。ブリックの電源を再投入するか、.rxe プログラムを開始/停止すると、基準が無効になります。タッチセンサーに対してホーミングし、絶対ターゲットに依存する前に zero_motor_position を再度呼び出してください。

グループコマンドは、1つのコントローラーロック内で連続したUSBパケットを使用してモーターを起動します。これらはMCP/LLMのラウンドトリップのずれを回避し、すべてのエンコーダーをまとめて監視しますが、ハードリアルタイムでも機械的に位相ロックされていません。二輪ロボットの場合、これは通常の走行に適しています。精密な同期にはNXT常駐制御プログラムが必要になる場合があります。

ハードウェア報告の制限

NXTファームウェアはすべてのポートの設定済み状態を報告しますが、アイドル状態のモーターが物理的に接続されているかどうかを安全に判断することはできません。したがって、ブリック全体のクエリは、モーターの存在を主張するのではなく、すべてのA/B/Cファームウェア状態を報告します。read_sensor またはセンサー駆動コマンドによってすでに設定されているセンサーポートは型付き値を表示します。他のセンサーポートは生のファームウェア状態を表示します。生の状態のクエリはポートを再設定したり、ハードウェアを一時的に通電したりしません。

.rxe プログラムが同じポートを制御している間は、直接MCPモーターコマンドを使用しないでください。

MCPを通じたPC側Pythonビヘイビア

標準のNXTはPythonを実行しません。このサーバーは代わりに、制限付きPythonビヘイビアをPC上に保存して実行できます。すべてのロボット操作は依然としてコントローラーの境界を越えるため、スクリプトはUSBを開いたり、NXT-Pythonセンサーをインスタンス化したり、独自のポーリングループを実装したりしません。

ビヘイビアの例:

def run(robot):
    robot.configure_sensor(1, "touch")

    for _ in range(5):
        robot.motor_until("C", 20, 1, "pressed")
        robot.motor_until("C", -20, 1, "released")

    robot.play_tone(440, 500)
    return "completed 5 touch cycles"

同じ例が behaviors/touch_cycle.py として含まれています。次のMCPツールを使用します:

validate_behavior(source)
submit_behavior(name, source)
list_behaviors()
get_behavior(name)
run_behavior(name, timeout_seconds=120)

スクリプトから見える robot インターフェースには以下が含まれます:

configure_sensor(port, sensor_type)
read_sensor(port, sensor_type)
read_sensor_raw(port, sensor_type=None)
zero_sensor_reference(port, sensor_type)
read_sensor_relative(port, sensor_type)
wait_sensor(port, sensor_type, condition, ...)
sensor_stream(port, sensor_type, ...)
log_start(channels, interval_ms=100, duration_seconds=10)
log_status(job_id)
log_stop(job_id)
log_export(job_id)
motor_until(port, power, sensor_port, condition, sensor_type="touch", ...)
motor_for_ticks(port, power, ticks, ...)
motor_position(port)
zero_motor_position(port)
motor_to(port, target_degrees, power=20, ...)
run_motor(port, power, regulated=True)
drive_sync(left_port, right_port, power, turn_ratio=0)
wait_motors(ports, ...)
stop_motor(port, brake=False)
run_motors(ports, powers, regulated=True)
stop_motors(ports, brake=False)
motors_relative(ports, powers, degrees, ...)
motors_absolute(ports, powers, target_degrees, ...)
motors_until(ports, powers, sensor_port, condition, ...)
state(format="text")
play_tone(frequency_hz=440, duration_ms=500)
play_sound_file(name, loop=False)
stop_sound()
sleep(seconds)

インポート、クラス、例外処理、プライベート属性へのアクセス、および文書化されたrobotメソッドと基本的な組み込み関数の外部への呼び出しは拒否されます。スクリプトは64 KiBに制限され、一度に1つだけ実行でき、run_behavior は1〜300秒の期限を受け入れます。スクリプトが終了するか例外を発生させると、すべてのモーターが停止します。

この検証は、robotインターフェースの外部への偶発的なアクセスを防ぐことを目的としています。これは悪意のあるコードに対するセキュリティサンドボックスではありません。MCPアクセスは信頼できるローカルユーザーにのみ許可してください。サーバーを起動する前に NXT_BEHAVIOR_DIR を設定して、ビヘイビアをサーバーの作業ディレクトリの下のデフォルトの behaviors ディレクトリ以外の場所に保存します。

コントローラーを直接インポートする代わりにMCP stdioを使用するコマンドラインのデモンストレーションの場合:

.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py list
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py submit touch_cycle behaviors\touch_cycle.py
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py run touch_cycle --timeout 120

最後のコマンドは物理的な移動を実行します。クライアントはMCPツールのみを呼び出します。MCPサーバーはビヘイビアをロードし、すべてのNXT通信を所有します。

ブリックなしでのテスト

$env:PYTHONPATH = "src"
py -3.11 -m pytest