webots-mcp-kit

webots-mcp-kit is a Windows-first toolkit for running Webots with a stable CLI, MCP server, controller SDK, bundled benchmarks, and structured world/controller authoring workflows. v2.9.0 extends the MonsterBorg hardening line from line-follow into obstacle avoidance, waypoint navigation, tuning analytics, and an optional Raspberry Pi physical parity gate on top of the existing e-puck and MonsterBorg runtime surfaces.

Support Matrix

Supported baseline: Windows, Webots R2025a, Python 3.11+, interactive-webots, e-puck, plus MonsterBorg 4WD Webots support and the Raspberry Pi physical-adapter lane on the current release line.

Unsupported Matrix

5-Minute Quickstart

From a repo checkout on a Windows machine with Webots R2025a installed:

pipx install webots-mcp-kit
powershell -ExecutionPolicy Bypass -File .\scripts\verify_install.ps1 -Runtime

That path verifies:

• doctor
• bundled benchmark discovery
• temporary controller scaffold + validate
• bundled world inspect
• a short real line-follower benchmark

MonsterBorg verification uses the same public script:

powershell -ExecutionPolicy Bypass -File .\scripts\verify_install.ps1 -RobotProfile monsterborg-4wd -Runtime

If pipx is not installed yet, use the helper:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\verify_install.ps1 -Runtime

Choose Your Path

• Connect an agent: start with First hour guide
• Write or edit a controller: start with Controller authoring and editing
• Inspect or edit a world: start with World authoring and editing
• Import an existing project and replay a session: start with Project import and session replay

For Teams

Use the team starter workspaces when you want a repeatable path that can be handed to another developer without extra setup decisions:

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap_workspace.ps1 -Starter line-follower -Destination .\workspaces\line-follower-demo
powershell -ExecutionPolicy Bypass -File .\scripts\upgrade_check.ps1 -Workspace .\artifacts\upgrade-check -Runtime

MonsterBorg starter workspaces:

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap_workspace.ps1 -Starter monsterborg-line-follower -Destination .\workspaces\monsterborg-line-follower
powershell -ExecutionPolicy Bypass -File .\scripts\upgrade_check.ps1 -Workspace .\artifacts\monsterborg-upgrade-check -RobotProfile monsterborg-4wd -Runtime

Use Team flows when you want the exact command sequence for:

• evaluator flow
• controller author flow
• world author flow
• importer and triage flow

Install And Upgrade

Primary install path:

pipx install webots-mcp-kit

Upgrade with the same tool:

pipx upgrade webots-mcp-kit

Repo-assisted install from a checkout:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Fallback path when you do not want pipx:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install webots-mcp-kit

Packaging, pinned-version, and wheel-install details live in PyPI install and upgrade. Upgrade and post-release verification live in Upgrade guide.

Troubleshooting

If install or runtime verification fails, start with Troubleshooting.

Bundled Scenarios

• line-follower: camera-based line tracking and the canonical first-success benchmark
• obstacle-avoidance: proximity-sensor or front-range obstacle avoidance
• waypoint-nav: waypoint navigation with benchmarked goal progress

Robot profiles:

• e-puck: stable bundled task-world baseline
• monsterborg-4wd: bundled support with generated templates, bundled Webots examples, and robot-aware controller/world/import flows

CLI And MCP Overview

Core CLI areas:

• runtime: doctor, session start/inspect/logs/export/replay/stop, benchmark list/run/report
• controller authoring: controller scaffold, controller inspect, controller edit, controller validate
• world authoring: world inspect, world validate, world edit
• zero-to-sim: project init, scenario init, scenario validate, scenario build, scenario describe, scenario doctor
• import/replay: project import, session export, session replay
• MCP bridge: mcp serve

Additive robot-aware flags:

• --robot-profile e-puck
• --robot-profile monsterborg-4wd

Core MCP tools:

• runtime: webots_session_start, webots_get_state, webots_get_sensors, webots_capture_camera, webots_run_benchmark
• world authoring: webots_world_inspect, webots_world_validate, webots_world_edit
• controller authoring: webots_controller_scaffold, webots_controller_inspect, webots_controller_validate, webots_controller_edit

Authoring workflows are supported on the stable release line, but the deeper schema surfaces remain experimental-foundation and additive. In v2.9.0, the MonsterBorg task-hardening line adds obstacle and waypoint variants, task-aware replay summaries, a benchmark matrix helper, and the optional Raspberry Pi physical parity gate.

MonsterBorg task-hardening extras:

• bundled variant specs under examples/monsterborg/line-follower/variants
• bundled variant specs under examples/monsterborg/obstacle-avoidance/variants
• bundled variant specs under examples/monsterborg/waypoint-nav/variants
• richer benchmark report and session replay task metrics for line-follow, obstacle, and waypoint
• python scripts/monsterborg_benchmark_matrix.py <report-or-export>... --output <json>
• python scripts/monsterborg_calibration_report.py --sim-export <dir> --physical-export <dir> --output <json>

Docs Map

• First hour guide
• Onboarding flows
• Team flows
• Troubleshooting
• PyPI install and upgrade
• Upgrade guide
• Version policy
• MonsterBorg physical adapter
• MonsterBorg physical runner
• Controller authoring and editing
• World authoring and editing
• Custom controller integration
• Zero-to-sim guide
• Project import and session replay
• MCP contracts
• Self-hosted runtime smoke
• Release checklist