webots-mcp-kit 2.8.0a1

Windows-first Webots developer toolkit with CLI, MCP server, controller SDK, and bundled benchmarks.

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. The v2.8.0-alpha.1 preview branch hardens MonsterBorg line-follow with richer track variants, stronger controller telemetry, and a sim-to-real calibration report on top of the existing e-puck and MonsterBorg runtime surfaces.

Support Matrix

Area	Supported
OS	Windows
Webots	R2025a
Python	3.11+
Runtime model	interactive-webots
Robot family	e-puck, MonsterBorg 4WD
Package distribution	PyPI + GitHub
Runtime workflows	doctor, session, benchmark, import/export/replay
Authoring workflows	controller scaffold/inspect/edit/validate, world inspect/validate/edit, scenario init/validate/build/doctor

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

Area	Not supported on v2.8.0-alpha.1
Runtime	Windows service runner, Linux, macOS, live MCP control of physical robots
Robotics stack	ROS2, multi-robot orchestration
World generation	free-form natural-language-to-world generation
Distribution	.exe, winget, standalone website, marketplace/app-directory packaging
Physical robot lane	general Linux runtime, non-MonsterBorg hardware adapters

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. On v2.8.0-alpha.1, the MonsterBorg line-follow hardening, variant bundle, and calibration report lane remain preview-scoped additions.

MonsterBorg line-follow preview extras:

• bundled variant specs under examples/monsterborg/line-follower/variants
• richer benchmark report and session replay line-follow metrics
• 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
• 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