ai2thor-mcp

ai2thor-mcp

一个 MCP 服务，可让大模型 Agent 控制 AI2-THOR 中的模拟家用机器人。机器人仅配备摄像头（没有机械臂）：它会四处观察，发现目的地——可见物体，以及根据深度信息检测到的可通行通道——并使用类似 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 路径，并在后台开始行驶。立即返回航点和预计到达时间。正在执行的目标会被抢占。
get_nav_status()	idle | planning | following | succeeded | canceled | failed(reason)，以及已行驶／剩余距离、百分比、预计到达时间和航点数量。
cancel_nav()	在一个步骤内让机器人停止。
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"：显示整个楼层平面图的固定正交视图。一次只能进行一段录制。
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）；跟随线程会以指定速度沿路径拐角行驶，并进行碰撞重试和一次重新规划，因此 get_nav_status 会显示真实的实时进度。
• 录制会在每个仿真步骤捕获第三方摄像头画面；按节奏运行的写入器会通过捆绑的 ffmpeg（imageio-ffmpeg）每个时钟周期写入一帧，因此 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/ 中捕获的真实帧测试夹具。

备注

• Agent 模式为 locobot（差速驱动，不具备操作能力）。
• data/recordings/ 是被 git 忽略的输出目录；data/example_* 是测试夹具。
• 使用 Claude Code 时，项目技能 /restart-ai2thor-mcp 会重启端口 8000 上的服务并进行健康检查。