ai2thor-mcp

ai2thor-mcp

LLM エージェントがシミュレーション上の家庭用ロボットを AI2-THORで操作できるようにする MCP サーバーです。ロボットはカメラのみを搭載しており（アームはありません）、 周囲を見回して目的地を発見します。目的地には、目に見える物体と深度情報から検出した通行可能な通路があります。そして、nav2 形式の非同期ナビゲーションで目的地まで移動します。俯瞰カメラで動作の mp4 動画を録画できます。

GPTPet のシミュレーションバックエンドとして構築されており、ツールの仕様は ROS2 nav2 の NavigateToPose のセマンティクス（非同期ゴール、ステータスのポーリング、キャンセル、 先行ゴールの置き換え）を反映しています。これにより、nav2+SLAM を実行する実機ロボットでも、後から同じ MCP インターフェースを実装できます。

ツール

ツール	内容
get_current_view()	番号付きの目的地マーカーを重ねたカメラフレームと、JSON リストを返します。リストには、物体（緑色のボックス。例："Fridge, 2.3 m ahead, closed, contains 2 items"）と通路（シアン色のボックス。ロボットが通れる幅の出入口、廊下、開口部）が含まれます。ID は安定していますが、マーカーの番号はビューごとに振り直されます。
set_nav_goal(destination_id, speed_mps=0.35)	目的地までの navmesh 経路を計画し、バックグラウンドで移動を開始します。ウェイポイントと ETA をすぐに返します。実行中のゴールは先行ゴールとして置き換えられます。
get_nav_status()	idle | planning | following | succeeded | canceled | failed(reason) と、移動距離／残り距離、進捗率、ETA、ウェイポイント数を返します。
cancel_nav()	1 ステップ以内にロボットを停止します。
list_destinations()	これまでに検出したすべての目的地を、ビューをまたいで返します。物体の ID は現在位置に再解決され、通路の ID は固定されたワールド座標のウェイポイントを示します。
get_map()	物体、ロボットの位置と向き、残りの経路、目的地、ゴールを含む上面図を返します。
do_move(action, moveMagnitude) / do_rotate(action, degrees)	手動操作です。実行中のナビゲーションを先行して置き換えます（nav2 のテレオペ動作）。
start_overhead_recording(mode)	mode="follow"（デフォルト）：カメラがロボットの約 2.3 m 上に浮かび、追従します。mode="scene"：間取り全体を固定の正投影ビューで映します。同時に録画できるのは 1 件です。
end_overhead_recording()	録画を確定し、ブラウザーで再生できる H.264 mp4 のパスを data/recordings/ 内に返します（リアルタイム録画のため、停止中の時間は静止フレームで保持されます）。

また、生のカメラフレームを取得できる MCP リソース view://rgb もあります。

セットアップ

Python 3.10〜3.12 と uv が必要です。初回実行時に AI2-THOR の Unity ビルド（約 0.5 GB）がダウンロードされ、Unity ウィンドウが開きます。シミュレーターは、最初のツール呼び出し時に遅延起動します。

uv sync            # add --extra dev for the test suite

実行

# streamable HTTP on 0.0.0.0:8000 (endpoint: /mcp, stateless)
uv run python/ai2thor_mcp/main.py --http

# stdio transport
uv run python/ai2thor_mcp/main.py

# pick a scene (default FloorPlan2, a single kitchen; RoboTHOR apartments
# like FloorPlan_Train1_3 have real doorways and corridors)
uv run python/ai2thor_mcp/main.py --http --scene FloorPlan_Train1_3

HTTP はステートレスなので、複数の MCP クライアントで同じシミュレーターインスタンスを共有できます。

クライアントの接続

Claude Code：

claude mcp add --transport http ai2thor http://localhost:8000/mcp

Claude Desktop は claude_desktop_config.json で stdio のみを使用するため、mcp-remote でブリッジします。

"ai2thor": {
  "command": "npx",
  "args": ["-y", "mcp-remote", "http://localhost:8000/mcp"]
}

仕組み

python/ai2thor_mcp/
├── main.py        MCP tools and wiring
├── sim.py         single lock-guarded owner of the AI2-THOR Controller
├── perception.py  depth → world backprojection; passage detection
├── describe.py    template descriptions + destination registry
├── annotate.py    numbered set-of-marks drawing on the frame
├── nav.py         nav2-style background goal follower
├── recorder.py    overhead mp4 recording (paced ffmpeg writer thread)
├── utils.py       top-down map rendering
└── config.py      all tunables (robot width, speeds, detection thresholds…)

• 通路は深度画像から検出します。点をワールド空間に逆投影し、極座標の自由空間プロファイルに分類してから、レベルセット走査で隙間を検出します（通路とは、両側の障害物より十分先まで障害物のないビンが連続している領域です）。床の可視性と navmesh 到達可能性を確認して窓や鏡を除外し、最小幅のフィルター（MIN_PASSAGE_WIDTH_M = 0.65）によって、ロボットが通れる隙間だけを残します。
• 経路計画には AI2-THOR の navmesh（GetShortestPath）を使用します。追従スレッドは指定速度でコーナーを移動し、衝突時の再試行と 1 回の再計画を行うため、get_nav_status には実際の進捗が表示されます。
• 録画では、シミュレーションの各ステップでサードパーティ製カメラのフレームをキャプチャします。ペース制御されたライターが同梱の ffmpeg （imageio-ffmpeg）に 1 ティックごとに 1 フレームをストリーミングするため、シミュレーターをブロックせずに mp4 を実時間に合わせられます。注意：AI2-THOR 5.0 では追加後のカメラを削除できないため、最初の録画以降は各ステップでカメラがレンダリングされます（わずかな負荷がかかります）。

テスト

uv run --extra dev pytest regression -m "not live"   # offline, no Unity
uv run --extra dev pytest regression -m live         # boots Unity, drives the robot

オフラインテストでは、解析的な深度シーンを使ったジオメトリ（合成した出入口は検出され、狭い隙間や何もない壁は検出されないこと）、運動学的な偽シミュレーターに対するナビゲーションの状態機械、レコーダーのホールドから壁時計までのフレームごとの書き込みを検証します。scripts/capture_fixture.py は、キャプチャした実フレームのフィクスチャを data/ に再生成します。

注意事項

• エージェントモードは locobot です（差動駆動、マニピュレーションなし）。
• data/recordings/ は Git で無視される出力先です。data/example_* はテスト用フィクスチャです。
• Claude Code では、プロジェクトスキル /restart-ai2thor-mcp がポート 8000 のサーバーを再起動し、ヘルスチェックを行います。