Gazebo

The Gazebo MCP Server enables you to control Gazebo simulations from an MCP client using the ROS2 Model Context Protocol. With it, you can start, pause, and stop simulations, spawn and manage robots, access sensor data, and perform dynamic world generation all through a standardized MCP interface. This makes it easier to build AI-powered tools that design, test, and evaluate robotic scenarios in Gazebo.

How to use

You interact with the Gazebo MCP Server by running it locally and then issuing MCP tool calls from your client. Start the server, connect your MCP client, and you can list models, spawn robots, query states, access sensors, and control the simulation lifecycle. The server automatically falls back to mock data when Gazebo isn’t available, so you can develop and test against a stable interface even without Gazebo running.

How to install

Prerequisites include a ROS2 distribution, Gazebo, Python, and a supported operating system. Follow these steps to install and run the Gazebo MCP Server.

# Prerequisites
# - ROS2 Humble installed
# - Modern Gazebo (Fortress, Garden, or Harmonic)
# - Python 3.10+
# - Ubuntu 22.04/24.04

# 1. Install ROS2 Humble
sudo apt update
sudo apt install ros-humble-desktop

# 2. Install Modern Gazebo for ROS2 Humble
sudo apt install ros-humble-ros-gz

# 3. Clone and set up the Gazebo MCP project
git clone https://github.com/yourusername/gazebo-mcp.git
cd gazebo-mcp

# 4. Source ROS2 and install Python dependencies
source /opt/ros/humble/setup.bash
pip install -r requirements.txt

# 5. Build the package (if using a ROS2 workspace)
colcon build
source install/setup.bash

# 6. Run the MCP server
python -m mcp.server.server

Additional setup and configuration

Configure the Gazebo MCP Server using environment variables to select the Gazebo backend, default world, and timeouts. The recommended backend is the modern Gazebo implementation.

# Use Modern Gazebo (default)
export GAZEBO_BACKEND=modern

# Use Classic Gazebo (deprecated)
export GAZEBO_BACKEND=classic

# Auto-detect automatically
export GAZEBO_BACKEND=auto

# Default world name (Modern only)
export GAZEBO_WORLD_NAME=default

# Service call timeout in seconds
export GAZEBO_TIMEOUT=5.0

Run the MCP server configuration for Claude Desktop Integration

If you want to connect Claude Desktop to the Gazebo MCP Server, configure the MCP entry to start the server with the appropriate environment and path settings.

{
  "mcpServers": {
    "gazebo": {
      "command": "python",
      "args": ["-m", "mcp.server.server"],
      "cwd": "/path/to/ros2_gazebo_mcp",
      "env": {
        "PYTHONPATH": "/path/to/ros2_gazebo_mcp/src",
        "ROS_DOMAIN_ID": "0",
        "GAZEBO_BACKEND": "modern",
        "GAZEBO_WORLD_NAME": "default",
        "GAZEBO_TIMEOUT": "5.0"
      }
    }
  }
}

Available tools

gazebo_list_models

List all models currently in the Gazebo simulation with optional ResultFilter support to reduce data payloads.

gazebo_spawn_model

Spawn a model from a URDF/SDF file or an XML string into the running Gazebo world.

gazebo_delete_model

Remove a model from the simulation by name.

gazebo_get_model_state

Query a model's pose and velocity.

gazebo_set_model_state

Set a model's pose or velocity to teleport or move it.

gazebo_list_sensors

List available sensors for a given model with optional filtering.

gazebo_get_sensor_data

Retrieve the latest data from a specified sensor (camera, LiDAR, IMU, GPS, etc.).

gazebo_subscribe_sensor_stream

Subscribe to a sensor stream and cache incoming data for processing.

gazebo_load_world

Validate a world file and provide loading instructions.

gazebo_save_world

Provide instructions for saving the current world state.

gazebo_get_world_properties

Query physics and scene properties of the Gazebo world.

gazebo_set_world_property

Update properties of the world, such as lighting and gravity.

gazebo_pause_simulation

Pause the physics simulation.

gazebo_unpause_simulation

Resume the physics simulation.

gazebo_reset_simulation

Reset the simulation to its initial state.

gazebo_set_simulation_speed

Set the rate at which the simulation runs.

gazebo_get_simulation_time

Query current simulation time and performance metrics.

gazebo_get_simulation_status

Get a comprehensive status of the simulation.