servidor ros2-mcp

ros2-mcp-server es un servidor basado en Python que integra el Protocolo de Contexto de Modelo (MCP) con ROS 2, lo que permite a los asistentes de IA controlar robots mediante temas de ROS 2. Procesa comandos mediante FastMCP y se ejecuta como un nodo de ROS 2, publicando mensajes de geometry_msgs/Twist en el tema /cmd_vel para controlar el movimiento del robot.

Esta implementación admite comandos como "avanzar a 0,2 m/s durante 5 segundos y detenerse", con el publicador /cmd_vel llamado pub_cmd_vel .

Características

Integración MCP : utiliza FastMCP para manejar comandos de clientes MCP (por ejemplo, Claude).
ROS 2 Native : funciona como un nodo ROS 2 y publica directamente en /cmd_vel .
Control basado en tiempo : admite comandos de movimiento basados en duración (por ejemplo, moverse durante un tiempo específico y detenerse).
Procesamiento asincrónico : combina asyncio de FastMCP con el bucle de eventos de ROS 2 para una operación eficiente.

Related MCP server: MCP Terminal

Prerrequisitos

ROS 2 : Distribución humilde instalada y obtenida.
Python : Versión 3.10 (necesaria para compatibilidad con ROS 2 Humble).
uv : Administrador de paquetes de Python para la gestión de dependencias.
Dependencias :
- rclpy : biblioteca cliente de Python para ROS 2 (instalada con ROS 2).
- fastmcp : marco FastMCP para la implementación del servidor MCP.
- numpy : requerido por los tipos de mensajes ROS 2.

Instalación

Clonar el repositorio :

git clone https://github.com/kakimochi/ros2-mcp-server.git
cd ros2-mcp-server

Configuración de la versión de Python : Este proyecto utiliza Python 3.10, según lo exige ROS 2 Humble. El archivo .python-version ya está configurado.
```
# .python-version content
3.10
```

Dependencias del proyecto : El archivo pyproject.toml está configurado con las dependencias necesarias:

# pyproject.toml content
[project]
name = "ros2-mcp-server"
version = "0.1.0"
description = "ROS 2 MCP Server"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "fastmcp",
    "numpy",
]

Crear entorno uv :
```
uv venv --python /usr/bin/python3.10
```
Activar el entorno virtual :
```
source .venv/bin/activate
```
Verá (.venv) aparecer al comienzo del símbolo del sistema, lo que indica que el entorno virtual está activo.
Instalar dependencias :
```
uv pip install -e .
```

Configuración del servidor MCP

Para usar este servidor con Claude u otros clientes MCP, debe configurarlo como servidor MCP. A continuación, le explicamos cómo configurarlo:

Para Claude Desktop

Abra la configuración de Claude Desktop y navegue hasta la sección de servidores MCP.

Agregue un nuevo servidor MCP con la siguiente configuración:

"ros2-mcp-server": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/ros2-mcp-server",
    "run",
    "bash",
    "-c",
    "export ROS_LOG_DIR=/tmp && source /opt/ros/humble/setup.bash && python3 /path/to/ros2-mcp-server/ros2-mcp-server.py"
  ],
  "transportType": "stdio"
}

Importante : Reemplace /path/to/ros2-mcp-server con la ruta real de su repositorio. Por ejemplo, si clonó el repositorio a /home/user/projects/ros2-mcp-server , deberá usar esa ruta.

Guarde la configuración y reinicie Claude.

Para Cline (extensión de VSCode)

En VSCode, abra la configuración de la extensión Cline haciendo clic en el ícono de Cline en la barra lateral.
Navegue a la sección de configuración de servidores MCP.

Agregue un nuevo servidor MCP con la siguiente configuración:

"ros2-mcp-server": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/ros2-mcp-server",
    "run",
    "bash",
    "-c",
    "export ROS_LOG_DIR=/tmp && source /opt/ros/humble/setup.bash && python3 /path/to/ros2-mcp-server/ros2-mcp-server.py"
  ],
  "transportType": "stdio"
}

Importante : reemplace /path/to/ros2-mcp-server con la ruta real a su repositorio, como en el ejemplo de Claude Desktop.

Puede activar o desactivar inmediatamente el servidor y verificar la conexión directamente desde la interfaz de configuración de Cline MCP sin necesidad de reiniciar VSCode o recargar la extensión.

Uso

Una vez configurado el servidor MCP, puedes usar Claude para enviar comandos al robot:

Ejemplo de comando : Pídale a Claude que mueva el robot hacia adelante a 0,2 m/s durante 5 segundos:
```
Please make the robot move forward at 0.2 m/s for 5 seconds.
```
Uso directo de la herramienta : también puedes utilizar la herramienta move_robot directamente:
```
{
  "linear": [0.2, 0.0, 0.0],
  "angular": [0.0, 0.0, 0.0],
  "duration": 5.0
}
```
Temas de Monitor ROS 2 : Verifique la salida del tema /cmd_vel :
```
ros2 topic echo /cmd_vel
```

Pruebas

Con un simulador :
- Inicie un simulador compatible con ROS 2 (por ejemplo, Gazebo con TurtleBot3):
  export TURTLEBOT3_MODEL=burger ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py
- Utilice Claude para enviar comandos de movimiento.
- Observa al robot moviéndose en Gazebo.
Con un robot real :
- Asegúrese de que su robot esté configurado correctamente para suscribirse al tema /cmd_vel .
- Utilice Claude para enviar comandos de movimiento.
- El robot debe moverse según los comandos.
Resultado esperado :
- El servidor registra comandos de movimiento y comandos de detención.
- Claude recibe una respuesta como: "Successfully moved for 5.0 seconds and stopped" .

Solución de problemas

Errores de registro de ROS 2 : si encuentra errores de directorio de registro, asegúrese de que la variable de entorno ROS_LOG_DIR esté configurada en un directorio escribible (por ejemplo, /tmp ).
Desajuste de versiones de Python : asegúrese de estar usando Python 3.10, ya que ROS 2 Humble está diseñado para esta versión.
Errores de conexión : si Claude informa errores de "Conexión cerrada", verifique que la configuración del servidor MCP sea correcta y que todas las dependencias estén instaladas.

Estructura del directorio

ros2-mcp-server/
├── ros2-mcp-server.py  # Main server script integrating FastMCP and ROS 2
├── pyproject.toml      # Project dependencies and metadata
├── .python-version     # Python version specification
├── .gitignore          # Git ignore file
└── README.md           # This file

Limitaciones

Tema único : Actualmente compatible con /cmd_vel con mensajes Twist . Ampliar ros2-mcp-server.py para otros temas o servicios.
Comandos básicos : Actualmente admite comandos de movimiento simples. Los comportamientos más complejos requieren una implementación adicional.

Licencia

MIT License

Copyright (c) 2025 kakimochi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Tenga en cuenta que este proyecto utiliza FastMCP , licenciado bajo la Licencia Apache 2.0. Los términos de dicha licencia también se aplican al uso de los componentes de FastMCP.

Expresiones de gratitud

Desarrollado con FastMCP y ROS 2 .

ROS2 MCP Server