robotmcp--ros-mcp-server/examples/1_turtlesim

Tutorial - Getting Started with ROS MCP Server and Turtlesim

Welcome to your first steps with the ROS MCP Server! This tutorial will guide you through using the ROS MCP Server with Turtlesim, the perfect "Hello World" robot for learning ROS integration.

Turtlesim is a lightweight simulator that demonstrates the fundamental concepts of ROS at the most basic level. It's ideal for understanding how the MCP server can interact with ROS systems before moving on to more complex robots.

What You'll Learn

By the end of this tutorial, you'll be able to:

• Launch Turtlesim on your ROS system
• Explore ROS topics and services
• Control the turtle using natural language commands through the MCP server
• Understand the basic concepts of ROS-MCP integration

Prerequisites

Before starting this tutorial, make sure you have:

✅ Any version of ROS installed (ROS1 Noetic, ROS2 Humble, or ROS2 Jazzy)
✅ Basic familiarity with terminal/command line
✅ The ROS MCP Server installed (see Installation Guide for setup instructions)

💡 Tip: If you don't have ROS installed yet, you can use our Docker Turtlesim example. However, we recommend this option only for users who are familiar with Docker and X11 forwarding settings. (We would like you to spend time exploring the Robot MCP server, not figuring out X11 forwarding on your machine!)

Step 1: Launch Turtlesim

First, let's get Turtlesim running on your system. The exact command depends on your ROS version:

ROS1 (e.g., Noetic)

Launch Turtlesim

1. Source your ROS environment:

   source /opt/ros/noetic/setup.bash # or /opt/ros/<ros_distro>/setup.bash
   

2. Launch Turtlesim:

   rosrun turtlesim turtlesim_node
   

You should see a window appear with a turtle in the center of a blue background.

Troubleshooting ROS1

• If you get "command not found", make sure you've sourced the ROS environment
• If the window doesn't appear, check your display settings (especially on WSL or remote connections)

ROS2 (e.g., Humble, Jazzy)

Launch Turtlesim

1. Source your ROS2 environment:

   source /opt/ros/humble/setup.bash  # or /opt/ros/jazzy/setup.bash
   

2. Launch Turtlesim:

   ros2 run turtlesim turtlesim_node
   

You should see a window appear with a turtle in the center of a blue background.

Troubleshooting ROS2

• If you get "command not found", make sure you've sourced the ROS2 environment
• If the window doesn't appear, check your display settings (especially on WSL or remote connections)

Step 2: Explore ROS Topics and Services

Now that Turtlesim is running, let's explore what's available in the ROS system. Open a new terminal and source your ROS environment, then try these commands:

List Available Topics

ROS1 (e.g., Noetic)

# Source ROS environment
source /opt/ros/noetic/setup.bash

# List all topics
rostopic list

# Monitor turtle position
rostopic echo /turtle1/pose

# Monitor velocity commands
rostopic echo /turtle1/cmd_vel

ROS2 (e.g., Humble, Jazzy)

# Source ROS2 environment (adjust for your version)
source /opt/ros/humble/setup.bash  # or /opt/ros/jazzy/setup.bash

# List all topics
ros2 topic list

# Monitor turtle position
ros2 topic echo /turtle1/pose

# Monitor velocity commands
ros2 topic echo /turtle1/cmd_vel

List Available Services

ROS1 (e.g., Noetic)

# List all services
rosservice list

# Get information about a specific service
rosservice info /turtle1/set_pen

ROS2 (e.g., Humble, Jazzy)

# List all services
ros2 service list

# Get information about a specific service
ros2 service type /turtle1/set_pen

Understanding Topics and Services

• Topics are like radio stations - nodes can publish data to topics and subscribe to receive data
• Services are like function calls - you can request a specific action and get a response
• The turtle's position is published on /turtle1/pose
• Movement commands are sent via /turtle1/cmd_vel
• Services like /turtle1/set_pen can change the turtle's drawing properties

Step 3: Install and Configure the MCP Server

If you haven't already set up the ROS MCP Server, follow the detailed Installation Guide. The MCP server can run on:

• Same machine as your ROS system (simplest setup)
• Different machine on the same local network (for remote control)

The installation guide covers:

• Installing the MCP server
• Configuring your language model client (Claude Desktop, etc.)
• Setting up rosbridge for communication

Step 4: Hands-on Exploration with MCP Server

Now for the fun part! Once your MCP server is connected, you can control the turtle using natural language. Here are some commands to try:

🚀 Basic Movement Commands

Try these natural language commands with your AI assistant:

Move the turtle forward

Turn the turtle left

Make the turtle go backward

Stop the turtle

📊 Information Queries

Ask your AI assistant about the robot's state:

Tell me about this robot.

What topics and services are available on the robot?

What is the turtle's current position?

🎨 Setup Commands

Reset the turtle to the center

Change the turtle's pen color to red

Spawn a new turtle

Clear the background

🎯 Advanced Commands

Try more complex behaviors:

Draw a square with the turtle

Move the turtle to position (5, 5)

Make the turtle follow a circular path

Draw a spiral pattern

💡 Pro Tips

• Be specific: Instead of "move", try "move forward at 2 m/s"
• Ask questions: "What can this robot do?" or "How do I make the turtle draw?"
• Experiment: Try combining commands like "draw a square, then change the pen color to green"
• Monitor: Use rostopic echo in a separate terminal to see the commands being sent

Troubleshooting

Common Issues

MCP Server Connection Issues

Problem: AI assistant can't connect to the robot

Solutions:

• Verify rosbridge is running: ros2 launch rosbridge_server rosbridge_websocket_launch.xml
• Check if MCP server is running and connected
• Ensure firewall allows WebSocket connections (port 9090)
• For remote connections, verify the robot's IP address

ROS Environment Issues

Problem: "command not found" errors

Solutions:

• Always source your ROS environment: source /opt/ros/[version]/setup.bash
• Add sourcing to your .bashrc for automatic setup
• Verify ROS installation with rosversion -d (ROS1) or ros2 doctor (ROS2)

Display Issues

Problem: Turtlesim window doesn't appear

Solutions:

• WSL users: Install X11 forwarding: sudo apt install x11-apps
• Remote connections: Use X11 forwarding: ssh -X username@hostname
• Docker users: Check X11 forwarding configuration

Permission Issues

Problem: Can't control the turtle

Solutions:

• Ensure you're not running multiple turtlesim instances
• Check if another process is controlling the turtle
• Restart turtlesim if commands aren't working

💡 Still Stuck?

If you're still having issues, check the official documentation for your ROS version:

• ROS1 Noetic Installation | Turtlesim Wiki
• ROS2 Humble Installation | Turtlesim Tutorial
• ROS2 Jazzy Installation | Turtlesim Tutorial

Additional Resources:

• ROS Answers - Community Q&A for specific problems
• ROS2 Doctor: Run ros2 doctor --report to diagnose ROS2 installation issues
• ROS Troubleshooting Guide (ROS1)

Next Steps

Congratulations! You've successfully controlled a robot using natural language. Here's what you can explore next:

🎯 Immediate Next Steps

1. Try more complex patterns: Draw shapes, follow paths, create animations
2. Experiment with services: Change colors, spawn multiple turtles, modify the environment
3. Monitor the system: Use rostopic echo to see the data flowing through ROS

🚀 Advanced Exploration

1. Explore other examples in this repository:

   • Gemini Integration - Advanced AI integration
   • Limo Mobile Robot - Real robot control
   • Unitree Go2 - Quadruped robot

2. Connect to real robots: Use the same MCP server with physical robots

3. Integrate with other tools: Combine with computer vision, planning algorithms, etc.

📚 Learning Resources

• ROS Documentation
• Turtlesim Tutorials
• MCP Protocol Documentation

---

Happy robot controlling! 🤖✨

This tutorial has shown you the fundamentals of ROS-MCP integration. The same principles apply to more complex robots - you're now ready to explore the exciting world of natural language robot control!