For users who want to test the MCP server without needing to install ROS, this is an example that provides a dockerized ROS2 container preinstalled with the simplest possible 'robot' in the ROS ecosystem - TurtleSim.

Turtlesim is a lightweight simulator for learning ROS / ROS 2. It illustrates what ROS does at the most basic level to give you an idea of what you will do with a real robot or a robot simulation later on.

Prerequisites

✅ Cross-Platform Support: This tutorial works on Linux, macOS, and Windows with proper X11/display forwarding setup. Each platform has specific requirements detailed below.

Before starting this tutorial, make sure you have the following installed:

All Platforms

Docker: Install Docker
Docker Compose: Usually comes with Docker Desktop, or install separately

Platform-Specific Requirements

macOS

XQuartz: Install from XQuartz website
Important: XQuartz setup can be complex - see macOS Setup section below for detailed instructions

Linux

X11 forwarding: sudo apt-get install x11-apps
Usually works out of the box with minimal setup

Windows

X Server: Install X410, VcXsrv, or another X Server from Microsoft Store
WSL recommended: Works best with Windows Subsystem for Linux

PowerShell and WSL (Windows)

Install Docker from installer or Microsoft Store
Open Docker Desktop > Settings > Resources > WSL Integration
Enable your distro (e.g., Ubuntu 22.04)
Verify installation: in PowerShell docker --version and in WSL docker --version

Quick Start

1. Build the Container

Navigate to the turtlesim example directory and build the Docker container:

cd examples/5_docker_turtlesim
docker compose build --no-cache turtlesim

2. Launch Turtlesim

Automatic Setup (Recommended)

The easiest way to launch turtlesim with proper X11 setup:

./scripts/launch.sh

This script automatically detects your OS and handles all platform-specific X11 configuration. It will:

macOS: Start XQuartz, detect display, configure IP-based forwarding
Linux: Set up X11 permissions with xhost +local:docker
Windows: Configure X server connection via host.docker.internal

Manual Setup (Advanced)

If you prefer manual control or the automatic script doesn't work:

macOS:

./scripts/launch_macos.sh

Linux (or Windows WSL):

./scripts/launch_linux.sh

Windows:

./scripts/launch_windows.sh

The container will automatically start both turtlesim and rosbridge websocket server. You should see:

A turtlesim window appear with a turtle
ROS Bridge WebSocket server running on ws://localhost:9090
Turtle teleop ready for keyboard input

3. Access the Container (Optional)

If you need to access the container for debugging or additional commands:

Launch the container in the background:

docker compose up -d

And attach to the container:

docker exec -it ros2-turtlesim bash

Once inside the container, you can manually launch turtle teleop to control the turtle:

source /opt/ros/${ROS_DISTRO}/setup.bash
ros2 run turtlesim turtle_teleop_key

This will allow you to use arrow keys or WASD to manually move the turtle around the turtlesim window.

Integration with MCP Server

Once turtlesim and rosbridge are running, you can connect the MCP server to control the turtle programmatically. Follow the installation guide for full setup instructions if you haven't already set up the MCP server.

Since it is running on the same machine, you can tell the LLM to connect to the robot on localhost.

Platform-Specific Setup

macOS Setup

macOS requires special X11 forwarding setup. Follow these steps carefully:

Step 1: Install XQuartz

Download and install from XQuartz website

Step 2: Configure XQuartz

Start XQuartz: open -a XQuartz
Wait for it to fully load (you'll see an xterm window)

Step 3: Detect Your Setup

# Check if XQuartz is running and which display it's using
ps aux | grep -i xquartz

# You should see something like:
# /opt/X11/bin/Xquartz :1 -listen tcp ...
# The `:1` or `:0` is your display number

Step 4: Get Your Machine IP

# Get your machine's IP address
ifconfig en0 | grep inet | awk '$1=="inet" {print $2}'
# Example output: 10.1.56.72

Step 5: Set Up Environment

# Set DISPLAY for your Mac (use the display number from Step 3)
export DISPLAY=:1  # or :0 depending on what you found

# Allow X11 connections
xhost +

# Set DISPLAY for Docker (use your IP from Step 4 + display number)
export DOCKER_DISPLAY=<YOUR_IP>  # Replace with your actual IP

Troubleshooting

macOS Display Issues

Problem: qt.qpa.xcb: could not connect to display

Solutions:

Check XQuartz is running:
```
ps aux | grep X11
```

Verify display number:

# Look for :0 or :1 in the Xquartz process
ps aux | grep Xquartz | grep -o ":[0-9]"

Check your IP address:
```
ifconfig en0 | grep inet
```

Set correct DOCKER_DISPLAY:

export DOCKER_DISPLAY="YOUR_IP:DISPLAY_NUMBER"
# Example: export DOCKER_DISPLAY="10.1.56.72:1"

Allow X11 connections:

export DISPLAY=:1  # Use your display number
xhost +

Problem: xhost: unable to open display ":0"

Solution: XQuartz might be using :1 instead of :0:

export DISPLAY=:1
xhost +

Linux Display Issues

Display issues on Linux

If you encounter display issues on Linux, run:

xhost +local:docker

Windows Display Issues

Display issues on Windows

For Windows users, make sure you install an X Server (X410) and set the DISPLAY:

$env:DOCKER_DISPLAY="host.docker.internal:0.0"

General Issues

Problem: Container starts but no window appears

Solutions:

Check if the window is hidden behind other windows
Look in Mission Control (macOS) or Alt+Tab (Windows/Linux)
Verify your DOCKER_DISPLAY is set correctly for your platform

Problem: libGL error: No matching fbConfigs or visuals found

Solution: This is just a warning and doesn't prevent the GUI from working. The turtlesim window should still appear.

Manual Launch (Alternative)

If the automatic launch isn't working or you prefer to launch turtlesim manually, you can run these commands inside the container:

# Access the container
docker exec -it ros2-turtlesim bash

# Source ROS2 environment
source /opt/ros/${ROS_DISTRO}/setup.bash

# Start turtlesim in one terminal
ros2 run turtlesim turtlesim_node

# In another terminal, start the teleop node
ros2 run turtlesim turtle_teleop_key

Testing Turtlesim

If you need to verify that turtlesim is working correctly:

ROS2 Topic Inspection

In a separate terminal, you can inspect the ROS2 topics:

# Access the container
docker exec -it ros2-turtlesim bash

# Source ROS2 environment
source /opt/ros/${ROS_DISTRO}/setup.bash

# List all topics
ros2 topic list

# Echo turtle position
ros2 topic echo /turtle1/pose

# Echo turtle velocity commands
ros2 topic echo /turtle1/cmd_vel

ROS Bridge WebSocket Server

The rosbridge websocket server is automatically started and available at ws://localhost:9090. You can test the connection using a WebSocket client or the MCP server.

To verify rosbridge is running, you can check the container logs:

docker logs ros2-turtlesim

Cleanup

To stop and remove the container:

docker-compose down

To remove the built image:

docker rmi ros-mcp-server_turtlesim

Next Steps

Now that you have turtlesim running, you can:

Try more complex commands like drawing shapes or following paths
Install ROS Locally to add more nodes and services
Explore other examples in this repository

This example provides a foundation for understanding how the MCP server can interact with ROS2 systems, from simple simulators like turtlesim to complex robotic platforms.