Webots MCP: AI-Agentic Robot Control for Robotics Simulation

Webots MCP is a powerful Model Context Protocol (MCP) server designed to bridge the gap between AI agents and robotics simulation. By integrating the MCP protocol with Cyberbotics Webots, this project enables seamless robot control of Nao robots using natural language and high-level reasoning.

---

🤖 Why Webots MCP?

Controlling robots in a robotics simulation typically requires deep knowledge of low-level APIs and physics engines. Webots MCP changes this by exposing complex robotic functions as simple tools that any AI agent (like Claude, Gemini, or Cursor) can understand and execute.

Whether you are a researcher or a developer, Webots MCP allows you to focus on high-level robot behavior while the server handles the intricate details of the MCP protocol and simulation synchronization.

✨ Features

• Natural Language Robot Control: Command your Nao robot to "wave its hand" or "look around" using AI agents.
• Visual Perception: AI agents can "see" through the robot's camera, enabling environmental reasoning within the robotics simulation.
• Safety-First Joint Limits: Built-in validation ensures motor commands stay within physical limits (radians) to prevent simulation errors.
• Advanced Motion Engine: Native support for complex .motion animation files like Tai Chi, waving, and walking.
• Multi-Robot Discovery: Webots MCP automatically tracks multiple robot instances in the simulation world.
• Real-time Telemetry: Access GPS positions, joint states, and robot status through the MCP protocol.

⚙️ How Webots MCP Works

The architecture of Webots MCP relies on a dual-layer communication bridge:

1. The MCP Server: A Node/Python service that translates AI agent tool calls into simulation commands.
2. The Controller Bridge: A low-level script running inside Webots that executes these commands on the Nao robot and returns telemetry data.

This separation ensures that Webots MCP remains responsive even during complex physical calculations in the robotics simulation.

🏗️ Architecture

graph LR
    subgraph "AI Agent Environment"
        A[MCP Client] <--> B[Webots MCP Server]
    end
    subgraph "Webots Simulation"
        B <--> C[Shared IPC /data/]
        C <--> D[Nao Controller]
        D <--> E[NAO Robot]
    end

🚀 Installation

1. Prerequisites

• Webots R2023a+
• Python 3.10+

2. Clone the Repository

git clone https://github.com/punithkrishnakeepudi/webots-mcp.git
cd webots-mcp

3. Setup Dependencies

pip install -r requirements.txt

🕹️ Usage Example

To connect Webots MCP to an AI client (like Cursor or Claude Desktop), add this entry to your mcp_config.json:

{
  "mcpServers": {
    "webots-mcp": {
      "command": "python",
      "args": ["/path/to/webots_mcp_custom/server.py"],
      "env": {
        "PYTHONPATH": "/path/to/webots_mcp_custom"
      }
    }
  }
}

Once connected, you can simply ask the agent:

"Check the Nao robot's camera and if you see an obstacle, turn the head 45 degrees left."

🛠️ Available Tools

Tool	Description
get_visual_perception	Captures the top camera image for AI reasoning.
get_robot_status	Returns telemetry (GPS, Joint angles, etc.).
play_motion	Executes high-level animations (wave, taichi, etc.).
set_head_position	Direct API for head robot control (Yaw/Pitch).
list_motions	Lists all available pre-recorded movements.

🗺️ Future Roadmap

• [ ] Support for Boston Dynamics Spot and Universal Robots models.
• [ ] Direct ROS2 (Robot Operating System) integration.
• [ ] Multi-agent collaborative swarm control.
• [ ] Advanced pathfinding tools integrated into Webots MCP.

---

⭐ Support the Project

If you find Webots MCP useful for your robotics simulation projects, please give us a star on GitHub! It helps developers discover the project and keeps the community growing.

⭐ Star this Repository

---

Developed by Punith Krishna