ROS2 MCP Server

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.

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

1. Clonar el repositorio :
   git clone https://github.com/kakimochi/ros2-mcp-server.git cd ros2-mcp-server
2. 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
3. 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", ]
4. Crear entorno uv :
   uv venv --python /usr/bin/python3.10
5. 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.
6. 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

1. Abra la configuración de Claude Desktop y navegue hasta la sección de servidores MCP.
2. 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.
3. Guarde la configuración y reinicie Claude.

Para Cline (extensión de VSCode)

1. En VSCode, abra la configuración de la extensión Cline haciendo clic en el ícono de Cline en la barra lateral.
2. Navegue a la sección de configuración de servidores MCP.
3. 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.
4. 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:

1. 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.
2. 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 }
3. Temas de Monitor ROS 2 : Verifique la salida del tema /cmd_vel :
   ros2 topic echo /cmd_vel

Pruebas

1. 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.
2. 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.
3. 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

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

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 .