Mbotmcp

This project uses Spring AI and the MCP protocol to achieve natural language control of the mBot2 robot. It includes a Spring Boot application, an MQTT message queue, and a Python script on the robot side, supporting AI calls for instructions such as exploration and turning.

Education and learning tools Home automation and IoT #Robot Control #Natural Language Interaction #MQTT Communication #AI Integration .Java

rating : 2.5 points

downloads : 7.4K

update time : 2025-04-23

Open Site

What is MBotMcp?

MBotMcp is an innovative system that allows you to control the mBot2 educational robot using everyday language (such as 'turn left' or 'explore the room'). It combines the natural language understanding ability of AI with physical robot control, implemented through the Spring framework and the MQTT communication protocol.

How to use MBotMcp?

Simply speak your instructions to the connected AI system, and the system will automatically convert them into commands that the robot can execute. For example, saying 'make the robot move forward and beep' will make the robot perform the corresponding actions.

Use cases

It is very suitable for educational demonstrations, research on the integration of AI and the Internet of Things, development of smart home prototypes, and any scenarios that require natural language control of robots.

Main Features

Natural Language Control

Control the robot using simple verbal or text instructions without programming knowledge.

MQTT Integration

Achieve reliable message delivery through the lightweight MQTT protocol.

Spring AI Integration

Leverage the powerful functions of the Spring framework to handle AI requests.

MCP Protocol Support

Use the Model Context Protocol to standardize the interaction between AI and devices.

Advantages

Control the robot without writing code

Intuitively demonstrate the combination of AI and the Internet of Things in educational scenarios

An open - source system that can be freely customized and extended

Support integration with multiple AI clients

Limitations

Requires the mBot2 hardware device

Depends on a WiFi network and an MQTT server

Currently only supports preset basic action instructions

Requires basic configuration knowledge to set network parameters

How to Use

Set up the MQTT server

Use the provided Docker Compose file to quickly start the MQTT message broker service.

Configure the robot

Upload the Python script to the mBot2 through the mBlock IDE and configure the WiFi and MQTT connection parameters.

Start the Spring application

After setting the environment variables, build and run the Spring Boot application.

Connect the AI client

Configure the AI client (such as Goose) to connect to the MCP server and start sending instructions.

Usage Examples

Classroom Demonstration

Demonstrate how AI understands natural language and controls physical devices in a programming class.

Smart Home Prototype

Simulate a robot performing tasks according to voice instructions in a smart home.

AI Research Experiment

Research the understanding and conversion abilities of different AI models for natural language instructions.

Frequently Asked Questions

What hardware devices are required to use this system?

Can more robot instructions be extended?

Which AI clients does the system support?

What if the robot loses connection?

Related Resources

Project GitHub Repository

Get the latest source code and documentation

mBot2 Official Documentation

Understand the robot's hardware specifications and basic programming

Spring AI Project

Learn about the Spring AI framework

Model Context Protocol Specification

Understand the technical details of the MCP protocol

🚀 MBotMcp

This project demonstrates how to control an mBot2 robot using Spring AI and the Model Context Protocol (MCP). With this setup, an AI model can control a physical robot through simple natural language commands such as "Explore" or "Turn left".

https://github.com/user-attachments/assets/a11d68c5-dc52-4dab-9741-bc1cf47e2ec9

✨ Features

The system consists of:

A Spring Boot application implementing the Model Context Protocol
An MQTT broker for message passing
Python code running on the mBot2 robot
AI client integration functionality

The Spring application exposes robot control commands as AI-callable functions, enabling the AI model to control the physical robot through natural language.

📦 Installation

Prerequisites

Java 21
Maven
mBot2 robot and mBlock IDE
MQTT broker (can be run in Docker)
Basic Java knowledge

Setup Instructions

1. MQTT Broker Setup (Optional if you don't have an existing broker)

Run the included Docker Compose file to set up the MQTT broker:

cd mbotmcp/assets
docker-compose up -d

This command creates a message queue for relaying commands between the application and the robot.

2. Configure the Spring Boot Application

Set the following environment variables:

MQTT_USERNAME=your_username # Leave empty if not configured
MQTT_PASSWORD=your_password # Leave empty if not configured
MQTT_SERVER_URI=tcp://your_server:1883

These variables tell your application how to connect to the MQTT broker.

3. mBot2 Setup

To upload the Python script to the mBot2:

Connect the mBot2 to your computer via USB.
Open mBlock IDE on your computer.
Click the "File" menu and select "Open".
Navigate to the /assets directory in the repository.
Open the mbot-mqtt.py file.
Modify the script to include your personal WiFi and MQTT configuration:

ssid = "<your wifi ssid>"
ssid_password = "<your wifi password>"
mqtt_ip = "<ip of the mqtt broker>"
mqtt_port = 1883
mqtt_user = "<your mqtt username>"
mqtt_password = "<your mqtt password>"

Upload the script to the mBot2.
Power on the mBot2.

4. Build the Spring Boot Application

mvn clean package

💻 Usage Examples

Testing the Setup

Ensure the MQTT broker is running.
Power on the mBot2 and ensure it is connected to WiFi.
Run the test client:

mvn test -Dtest=ClientStdioTest

Observe the robot execute the "Beep" command and light up the blue LED!

Available Robot Commands

The BotService class defines all the MCP tools that your robot can understand:

mbotExplore() - Execute the 'Explore' routine
mbotStop() - Stop the robot
mbotBeep() - Make the robot beep
mbotLeft() - Turn the robot left
mbotRight() - Turn the robot right
mbotForward() - Move the robot forward
mbotBackward() - Move the robot backward

📚 Documentation

This project demonstrates how to enable an AI model to control a physical robot through natural language processing (NLP). You can use this project as a starting point for more complex robot applications.

⚠️ Important Note

When using this project, ensure that you comply with all safety and legal regulations. The author is not responsible for any damage caused by improper use.