rosbridge-mcp

rosbridge-mcp es un servidor del Model Context Protocol que conecta agentes de IA (Claude Desktop, Cursor, VS Code y cualquier otro cliente MCP) a robots que ejecutan ROS 2, a través del protocolo estándar rosbridge v2 (WebSocket + JSON). Ejecutas rosbridge_server en tu robot o máquina ROS; este servidor MCP se conecta a él a través de la red y expone 11 herramientas que permiten a la IA observar tópicos, inspeccionar el grafo ROS y el árbol TF, ver a través de la cámara del robot, publicar mensajes, llamar servicios y ejecutar acciones de ROS 2 — sin necesidad de instalar ROS en la máquina donde se ejecuta el cliente de IA.

Arquitectura

+--------------------+   stdio (MCP)   +----------------+   WebSocket/JSON   +------------------+   DDS   +---------+
|  AI client         | <-------------> | rosbridge-mcp  | <----------------> | rosbridge_server | <-----> |  ROS 2  |
|  (Claude, Cursor,  |                 |  (this server) |    rosbridge v2    |  (on the robot)  |         |  graph  |
|   VS Code, ...)    |                 |                |      protocol      |                  |         |         |
+--------------------+                 +----------------+                    +------------------+         +---------+

Related MCP server: ROS2 MCP Server

Inicio rápido (60 segundos)

pip install git+https://github.com/hieutachi/rosbridge-mcp.git

O, una vez publicado: pip install rosbridge-mcp (PyPI — próximamente).

Añádelo a la configuración de tu cliente MCP (consulta las guías específicas para cada cliente más abajo para conocer las ubicaciones exactas de los archivos):

{
  "mcpServers": {
    "rosbridge": {
      "command": "rosbridge-mcp",
      "env": { "ROSBRIDGE_URL": "ws://<robot-ip>:9090" }
    }
  }
}

Luego pregúntale a tu agente: "¿Qué tópicos tiene el robot?"

Elige tu ruta

Elige la guía que se adapte a ti — cada una es autocontenida, no necesitas leer el resto de este README primero:

Herramientas

11 herramientas en total. Todas las herramientas devuelven JSON. Las cargas útiles de mensajes y argumentos utilizan la misma representación JSON de mensajes ROS que usa rosbridge (los nombres de campo coinciden con las definiciones .msg/.srv/.action).

list_topics

Lista todos los tópicos con sus tipos de mensaje. Sin parámetros.

{"topics": [
  {"name": "/chatter", "type": "std_msgs/msg/String"},
  {"name": "/cmd_vel", "type": "geometry_msgs/msg/Twist"},
  {"name": "/scan",    "type": "sensor_msgs/msg/LaserScan"}
]}

list_nodes

Lista todos los nodos en ejecución. Sin parámetros.

{"nodes": ["/talker", "/listener", "/rosapi"]}

list_services

Lista todos los servicios disponibles. Sin parámetros.

{"services": ["/rosapi/topics", "/rosapi/nodes", "/reset_odometry"]}

get_topic_snapshot

Se suscribe a un tópico, recoge mensajes, se desuscribe. Parámetros: topic (obligatorio), count (por defecto 1), timeout segundos (por defecto 5.0), msg_type (opcional, normalmente detectado automáticamente por rosbridge).

Entrada: {"topic": "/chatter", "count": 2, "timeout": 3.0}

{"topic": "/chatter", "requested": 2, "received": 2,
 "messages": [{"data": "Hello World: 41"}, {"data": "Hello World: 42"}],
 "timed_out": false}

Si el tópico está en silencio, received es menor que requested y timed_out es true — la herramienta nunca se cuelga más tiempo del indicado en timeout.

publish_message (mutante)

Anuncia un tópico y publica un mensaje JSON. Parámetros: topic, msg_type (tipo completo de ROS 2, ej. geometry_msgs/msg/Twist), message (objeto JSON que coincide con el tipo).

Entrada:

{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist",
 "message": {"linear": {"x": 0.1, "y": 0.0, "z": 0.0},
             "angular": {"x": 0.0, "y": 0.0, "z": 0.2}}}

Salida: {"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}

call_service (mutante)

Llama a cualquier servicio ROS. Parámetros: service (obligatorio), args (objeto JSON, por defecto {}), timeout segundos (por defecto 10.0).

Entrada: {"service": "/rosapi/topic_type", "args": {"topic": "/scan"}}

{"service": "/rosapi/topic_type", "success": true,
 "values": {"type": "sensor_msgs/msg/LaserScan"}}

En caso de fallo, la herramienta devuelve {"success": false, "error": "..."} en lugar de lanzar una excepción.

send_action_goal (mutante)

Envía un objetivo a un servidor de acciones ROS 2 (navegación, movimiento de brazo, ...). Parámetros: action_name, action_type (tipo completo con /action/, ej. nav2_msgs/action/NavigateToPose), goal (objeto JSON, por defecto {}), timeout segundos (por defecto 30, limitado a ≤ 120), wait_for_result (por defecto true).

Entrada: {"action_name": "/fibonacci", "action_type": "test_msgs/action/Fibonacci", "goal": {"order": 5}}

{"action": "/fibonacci", "goal_id": "send_action_goal:7", "success": true,
 "status": 4, "status_text": "succeeded",
 "values": {"sequence": [0, 1, 1, 2, 3, 5]},
 "last_feedback": {"partial_sequence": [0, 1, 1, 2, 3]}}

Con wait_for_result: false la herramienta devuelve {"goal_id": ..., "result_pending": true} inmediatamente — pasa ese goal_id a cancel_action_goal para detener el objetivo más tarde. Requiere una versión de rosbridge_suite con soporte para acciones de ROS 2; contra un rosbridge más antiguo, la herramienta devuelve un error recomendando una actualización en lugar de colgarse.

cancel_action_goal (mutante)

Cancela un objetivo de acción previamente enviado. Parámetros: action_name, goal_id (de send_action_goal).

Salida: {"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}

get_tf_tree

Toma una instantánea del árbol TF (transformación de coordenadas) del robot escuchando brevemente /tf y /tf_static. Parámetros: timeout segundos (por defecto 2.0, limitado a ≤ 10).

{"frame_count": 3,
 "frames": {
   "base_link": {"parent": "odom", "translation": {"x": 1.0, "y": 0.0, "z": 0.0},
                  "rotation": {"x": 0, "y": 0, "z": 0, "w": 1}, "source": "dynamic"},
   "laser":     {"parent": "base_link", "...": "...", "source": "static"}},
 "tree": {"odom": ["base_link"], "base_link": ["laser"]},
 "roots": ["odom"]}

get_camera_image

Captura un fotograma de un tópico de cámara como base64, para que los modelos con capacidad de visión puedan ver lo que ve el robot. Parámetros: topic (preferiblemente un tópico sensor_msgs/msg/CompressedImage, ej. /camera/image_raw/compressed), timeout segundos (por defecto 5.0, limitado a ≤ 30).

Salida: {"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234} (los tópicos Image sin procesar adicionalmente devuelven width/height/encoding). Los fotogramas de más de 4 MB no se devuelven — la herramienta responde con metadatos más un error sugiriendo un tópico comprimido.

get_connection_status

Informa del estado de la conexión y del modo de solo lectura. Sin parámetros.

{"url": "ws://localhost:9090", "connected": true,
 "connected_since_unix": 1786903978.1, "active_subscriptions": [],
 "pending_service_calls": 0, "readonly": false}

Ejemplo de conversación

Tú: ¿Qué está viendo el robot ahora mismo?

Agente: (llama a list_topics, encuentra /scan de tipo sensor_msgs/msg/LaserScan, luego llama a get_topic_snapshot con {"topic": "/scan", "count": 1}) El escáner láser reporta 360 lecturas de rango. El obstáculo más cercano está a unos 0.4 m aproximadamente a 90° a la izquierda; el espacio directamente al frente está despejado durante al menos 2.5 m.

Tú: Bien, avanza lentamente un momento.

Agente: (llama a publish_message con {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}) Publicado un comando de velocidad hacia adelante de 0.1 m/s. Dime cuándo parar y publicaré velocidad cero.

Para visión e IA corpórea

Dos de las herramientas de solo lectura existen específicamente para fundamentar los modelos de lenguaje visual en la realidad física del robot:

• get_camera_image devuelve un fotograma real de la cámara como base64 — un modelo con capacidad de visión (Claude, GPT-4o, o un front-end de política VLA) puede literalmente mirar a través de la cámara del robot antes de decidir qué hacer.

• get_tf_tree proporciona al modelo el esqueleto espacial del robot — qué marcos existen (map, odom, base_link, camera, gripper) y cómo están posicionados entre sí.

Combinado con get_topic_snapshot (lidar, odometría, estados de articulaciones) y send_action_goal (navegación, manipulación), esto cubre el bucle observar → razonar → actuar que los agentes de visión y acción necesitan, a través de un WebSocket simple, sin instalación de ROS en el lado del modelo. Ambas herramientas de percepción funcionan en modo de solo lectura, por lo que puedes ejecutar un agente de "mira pero no toques" de forma segura.

Configuración

Seguridad

Permitir que un modelo de lenguaje publique /cmd_vel en un robot físico es un riesgo real. Establece ROSBRIDGE_MCP_READONLY=true para ejecutar en modo de solo lectura: publish_message, send_action_goal y cancel_action_goal son rechazados, y call_service solo permite una lista blanca fija de servicios de introspección de /rosapi de solo lectura conocidos (topics, nodes, services, types, get_param, get_time, ...) — cualquier cosa que no esté en la lista, incluidos servicios futuros desconocidos de /rosapi, es rechazada. Las herramientas de percepción de solo lectura (get_topic_snapshot, get_tf_tree, get_camera_image) siguen funcionando. Recomendamos encarecidamente comenzar en modo de solo lectura con hardware real — consulta la lista de verificación de seguridad completa para robots reales y el modelo de seguridad de despliegue en SECURITY.md.

Privacidad y aspectos legales

Sin telemetría, sin recopilación de datos. Auditado (2026-08): la única conexión de red que este paquete abre alguna vez es el WebSocket hacia la ROSBRIDGE_URL que configures — no hay análisis, ni llamadas a casa, ni informes de fallos, ni llamadas HTTP ocultas, y el código no contiene registro del contenido de los mensajes en disco. El servidor simulado incluido se vincula solo a 127.0.0.1. Los datos del robot devueltos por las herramientas van exclusivamente a tu cliente MCP (que los reenvía al LLM que hayas elegido — esa parte está bajo tu control, no bajo el nuestro).

Cumplimiento de licencias. Todas las dependencias de tiempo de ejecución y transitivas tienen licencias compatibles con la licencia MIT de este proyecto — directas: fastmcp (Apache-2.0), websockets (BSD-3-Clause); transitivas clave: mcp (MIT), pydantic (MIT), starlette (BSD-3-Clause), httpx (BSD-3-Clause), anyio (MIT), cryptography (Apache-2.0/BSD-3). Una dependencia transitiva, certifi, es MPL-2.0 — un copyleft a nivel de archivo que solo se aplica a modificaciones de los propios archivos de certifi y es compatible con el uso y redistribución MIT. No hay código GPL/AGPL/propietario en ningún lugar del árbol de dependencias, y todo el código en este repositorio es trabajo original escrito para este proyecto.

Preguntas frecuentes

¿Necesito tener ROS instalado donde se ejecuta el cliente de IA? No. Solo Python 3.10+. ROS y rosbridge se ejecutan en el robot (o en Docker, o en un simulador); este servidor se comunica con ellos a través de WebSocket.

¿Funciona con ROS 1? El protocolo rosbridge v2 es el mismo, por lo que las operaciones básicas también funcionan contra un rosbridge_server de ROS 1 — usa nombres de tipo de ROS 1 (std_msgs/String). Solo ROS 2 se prueba en CI.

El agente indica que no puede conectarse. Verifique que rosbridge esté en ejecución (ros2 launch rosbridge_server rosbridge_websocket_launch.xml), que ROSBRIDGE_URL apunte al host/puerto correcto y que el puerto 9090 sea accesible (firewall). Cada guía en docs/ tiene una sección de solución de problemas.

¿Puedo probarlo sin ningún robot o simulador? Sí — python -m rosbridge_mcp.mock_server 9090 inicia un rosbridge falso con temas precargados, luego configure ROSBRIDGE_URL en ws://localhost:9090.

¿Se envían mis datos a algún lugar? El servidor solo se conecta a la ROSBRIDGE_URL que usted configure. Los datos de los temas se devuelven a su cliente MCP, que los reenvía al LLM que usted utilice — trate los datos de los sensores en consecuencia.

Hoja de ruta

Plan por etapas con objetivos, entregables y recursos necesarios para cada etapa: consulte ROADMAP.md. Lo más destacado: v0.2 cliente de acciones + TF + capturas de cámara (completado en v0.2.0), v0.3 transporte HTTP + imagen Docker + autenticación/TLS de rosbridge, v0.4 flotas multirobot + recursos MCP (URDF/mapa), v1.0 API estable + listado en el registro oficial de MCP + ejemplos de Gazebo/Isaac Sim.

Apoye este proyecto

rosbridge-mcp es construido y mantenido por una persona, a tiempo parcial, en su etapa inicial. Lo que existe hoy es real y probado: 11 herramientas que cubren temas, servicios, acciones de ROS 2, TF y capturas de cámara; 43 pruebas automatizadas que se ejecutan en CI en cada commit; documentación por escenario para 5 perfiles de usuario; un modo de seguridad de solo lectura con una lista blanca de servicios; y una base de código auditada sin telemetría.

Lo que la hoja de ruta necesita para hacerse realidad, expuesto honestamente:

• v0.3 (despliegue y seguridad): semanas de desarrollo a tiempo parcial, una pequeña VM en la nube o un runner autoalojado para la compilación de imágenes Docker y, lo más importante, un revisor orientado a la seguridad para la capa de autenticación/TLS de rosbridge.

• v0.4 (flotas): acceso a 2 o más instancias de robots o simuladores en ejecución simultánea, y comentarios de diseño de un laboratorio de robótica real (buscando un socio piloto académico o industrial).

• v1.0 (estabilidad y ecosistema): tiempo sostenido de mantenimiento (2 días/semana durante un trimestre), una estación de trabajo GPU clase RTX para la validación con Isaac Sim — la principal solicitud de hardware de toda la hoja de ruta — y, opcionalmente, un robot de bajo costo ($1–3k) para CI hardware-in-the-loop.

Cómo puede ayudar, en orden creciente de esfuerzo:

1. Dé una estrella al repositorio — la visibilidad ayuda genuinamente a que un proyecto temprano obtenga contribuyentes.

2. Pruébelo en su robot o simulador y abra un issue con su distribución de ROS y versión de rosbridge — los informes de compatibilidad son la forma más barata de hacerlo robusto.

3. Contribuya con un PR — docs/development.md explica la base de código en 10 minutos, y cada elemento de la hoja de ruta es reclamable.

4. Patrocine o asóciese — si su laboratorio o empresa puede ofrecer tiempo de simulador, hardware, una estación de trabajo GPU o tiempo de desarrollo financiado, póngase en contacto a través de github.com/hieutachi.

Recursos relacionados

Si se está iniciando en la robótica, el libro electrónico Robotics RL & UAV es un recurso de aprendizaje complementario del autor que cubre el aprendizaje por refuerzo y la robótica UAV.

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md y la guía de desarrollo. Firme sus commits (DCO).

Licencia

MIT — consulte LICENSE. Las licencias de las dependencias son permisivas y compatibles: fastmcp (Apache-2.0), websockets (BSD-3-Clause). Sin dependencias GPL/AGPL.

Tóm tắt tiếng Việt

rosbridge-mcp là một MCP server cầu nối giữa AI agent (Claude Desktop, Cursor, VS Code...) và robot chạy ROS 2 thông qua giao thức rosbridge (WebSocket + JSON). Không cần cài ROS trên máy chạy AI client.

Tài liệu được chia theo từng kịch bản — chọn đúng hướng dẫn cho bạn trong thư mục docs/:

• Dùng Claude Desktop — cấu hình JSON từng bước trên Windows/macOS/Linux

• Dùng Cursor / VS Code — cấu hình mcp.json trong editor

• Chưa có robot — chạy thử với Docker (ros:humble + rosbridge) hoặc TurtleBot3/Gazebo, hoặc mock server đi kèm

• Có robot thật — checklist an toàn: bật ROSBRIDGE_MCP_READONLY=true trước, đọc /odom, /scan để hiểu robot rồi mới mở quyền publish /cmd_vel

• Developer — kiến trúc code, cách thêm tool mới, chạy test với mock (không cần ROS)

11 tool: list_topics, list_nodes, list_services, get_topic_snapshot, publish_message, call_service, send_action_goal, cancel_action_goal, get_tf_tree, get_camera_image, get_connection_status. Bật ROSBRIDGE_MCP_READONLY=true để chặn mọi thao tác ghi (publish, action) khi làm việc với robot thật — các tool đọc (TF, camera, topic) vẫn hoạt động bình thường.

Tài liệu học kèm theo của tác giả: Robotics RL & UAV ebook — ebook về học tăng cường (reinforcement learning) và robot UAV.