# Webots MCP: AI-Agentic Robot Control for Robotics Simulation

[![GitHub stars](https://img.shields.io/github/stars/punithkrishnakeepudi/webots-mcp.svg?style=social&label=Star)](https://github.com/punithkrishnakeepudi/webots-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![FastMCP](https://img.shields.io/badge/MCP-FastMCP-blue.svg)](https://modelcontextprotocol.io)

**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

```mermaid
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
```bash
git clone https://github.com/punithkrishnakeepudi/webots-mcp.git
cd webots-mcp
```

### 3. Setup Dependencies
```bash
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`:

```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](https://github.com/punithkrishnakeepudi/webots-mcp)

---
Developed by [Punith Krishna](https://github.com/punithkrishnakeepudi)