webots-mcp-kit 2.2.0

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 for e-puck task worlds. v2.2.0 focuses on team adoption: starter workspaces, repeatable upgrade checks, and clearer team-facing docs on top of the existing runtime and authoring surface.

Support Matrix

Area	Supported
OS	Windows
Webots	R2025a
Python	3.11+
Runtime model	interactive-webots
Robot family	e-puck
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.

Unsupported Matrix

Area	Not supported in v2.2.0
Runtime	Windows service runner, Linux, macOS
Robotics stack	ROS2, multi-robot orchestration
World generation	free-form natural-language-to-world generation
Distribution	.exe, winget, standalone website, marketplace/app-directory packaging

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

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

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 obstacle avoidance
• waypoint-nav: waypoint navigation with benchmarked goal progress

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

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.

Docs Map

• First hour guide
• Onboarding flows
• Team flows
• Troubleshooting
• PyPI install and upgrade
• Upgrade guide
• Version policy
• 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