rosbridge-mcp

rosbridge-mcp — это сервер Model Context Protocol, который подключает AI-агентов (Claude Desktop, Cursor, VS Code и любые другие MCP-клиенты) к роботам, работающим под управлением ROS 2, через стандартный протокол rosbridge v2 (WebSocket + JSON). Вы запускаете rosbridge_server на своём роботе или ROS-машине; этот MCP-сервер подключается к нему по сети и предоставляет 11 инструментов, позволяющих AI наблюдать за топиками, исследовать граф ROS и дерево TF, видеть через камеру робота, публиковать сообщения, вызывать сервисы и управлять действиями ROS 2 — без необходимости установки ROS на машине, где работает AI-клиент.

Архитектура

+--------------------+   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

Быстрый старт (60 секунд)

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

Или, после публикации: pip install rosbridge-mcp (PyPI — скоро).

Добавьте в конфигурацию вашего MCP-клиента (см. руководства для конкретных клиентов ниже для точного расположения файлов):

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

Затем спросите своего агента: "Какие топики есть у робота?"

Выберите свой путь

Выберите руководство, которое подходит вам — каждое из них самодостаточно, вам не нужно читать остальную часть этого README сначала:

Инструменты

Всего 11 инструментов. Все инструменты возвращают JSON. Полезные нагрузки сообщений и аргументов используют то же JSON-представление ROS-сообщений, что и rosbridge (имена полей соответствуют определениям .msg/.srv/.action).

list_topics

Список всех топиков с их типами сообщений. Без параметров.

{"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

Список всех запущенных узлов. Без параметров.

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

list_services

Список всех доступных сервисов. Без параметров.

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

get_topic_snapshot

Подписаться на топик, собрать сообщения, отписаться. Параметры: topic (обязательный), count (по умолчанию 1), timeout секунд (по умолчанию 5.0), msg_type (необязательный, обычно определяется автоматически rosbridge).

Вход: {"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}

Если топик молчит, received меньше requested, а timed_out равно true — инструмент никогда не зависает дольше timeout.

publish_message (мутирующий)

Объявить топик и опубликовать одно JSON-сообщение. Параметры: topic, msg_type (полный тип ROS 2, например geometry_msgs/msg/Twist), message (JSON-объект, соответствующий типу).

Вход:

{"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}}}

Выход: {"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}

call_service (мутирующий)

Вызвать любой ROS-сервис. Параметры: service (обязательный), args (JSON-объект, по умолчанию {}), timeout секунд (по умолчанию 10.0).

Вход: {"service": "/rosapi/topic_type", "args": {"topic": "/scan"}}

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

При ошибке инструмент возвращает {"success": false, "error": "..."} вместо исключения.

send_action_goal (мутирующий)

Отправить цель на сервер действий ROS 2 (навигация, движение манипулятора и т.д.). Параметры: action_name, action_type (полный тип с /action/, например nav2_msgs/action/NavigateToPose), goal (JSON-объект, по умолчанию {}), timeout секунд (по умолчанию 30, ограничено ≤ 120), wait_for_result (по умолчанию true).

Вход: {"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]}}

С wait_for_result: false инструмент немедленно возвращает {"goal_id": ..., "result_pending": true} — передайте этот goal_id в cancel_action_goal, чтобы остановить цель позже. Требуется версия rosbridge_suite с поддержкой действий ROS 2; при старой версии rosbridge инструмент возвращает ошибку с рекомендацией обновления, а не зависает.

cancel_action_goal (мутирующий)

Отменить ранее отправленную цель действия. Параметры: action_name, goal_id (из send_action_goal).

Выход: {"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}

get_tf_tree

Снимок дерева TF (координатных преобразований) робота путём кратковременного прослушивания /tf и /tf_static. Параметры: timeout секунд (по умолчанию 2.0, ограничено ≤ 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

Захватить один кадр с топика камеры в base64, чтобы модели, способные к зрению, могли видеть то, что видит робот. Параметры: topic (предпочтительно топик sensor_msgs/msg/CompressedImage, например /camera/image_raw/compressed), timeout секунд (по умолчанию 5.0, ограничено ≤ 30).

Выход: {"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234} (сырые топики Image дополнительно возвращают width/height/encoding). Кадры размером более 4 МБ не возвращаются — инструмент отвечает метаданными и ошибкой с предложением использовать сжатый топик.

get_connection_status

Сообщить состояние подключения и режим только для чтения. Без параметров.

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

Пример диалога

Вы: Что сейчас видит робот?

Агент: (вызывает list_topics, находит /scan типа sensor_msgs/msg/LaserScan, затем вызывает get_topic_snapshot с {"topic": "/scan", "count": 1}) Лазерный сканер сообщает о 360 показаниях дальности. Ближайшее препятствие находится примерно в 0,4 м слева под углом около 90°; пространство прямо перед роботом свободно как минимум на 2,5 м.

Вы: Хорошо, медленно поезжай вперёд на мгновение.

Агент: (вызывает publish_message с {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}) Опубликована команда движения вперёд со скоростью 0,1 м/с. Скажите, когда остановиться, и я опубликую нулевую скорость.

Для зрительного и воплощённого AI

Два инструмента только для чтения существуют специально для того, чтобы grounded vision-language модели в физической реальности робота:

• get_camera_image возвращает реальный кадр с камеры в base64 — модель, способная к зрению (Claude, GPT-4o или фронтенд политики VLA), может буквально смотреть через камеру робота, прежде чем решить, что делать.

• get_tf_tree предоставляет модели пространственный скелет робота — какие фреймы существуют (map, odom, base_link, camera, gripper) и как они расположены относительно друг друга.

В сочетании с get_topic_snapshot (лидар, одометрия, состояния суставов) и send_action_goal (навигация, манипуляции) это покрывает цикл наблюдение → рассуждение → действие, необходимый агентам зрения и действия, через обычный WebSocket, без установки ROS на стороне модели. Оба инструмента восприятия работают в режиме только для чтения, поэтому вы можете безопасно запустить агента "смотри, но не трогай".

Конфигурация

Безопасность

Позволять языковой модели публиковать /cmd_vel на физическом роботе — это реальный риск. Установите ROSBRIDGE_MCP_READONLY=true, чтобы запустить в режиме только для чтения: publish_message, send_action_goal и cancel_action_goal будут отклонены, а call_service разрешит только фиксированный белый список известных сервисов интроспекции /rosapi только для чтения (topics, nodes, services, types, get_param, get_time, ...) — всё, что не в списке, включая неизвестные будущие сервисы /rosapi, будет отклонено. Инструменты восприятия только для чтения (get_topic_snapshot, get_tf_tree, get_camera_image) продолжают работать. Мы настоятельно рекомендуем начинать в режиме только для чтения с реальным оборудованием — см. полный чек-лист безопасности для реального робота и модель безопасности развёртывания в SECURITY.md.

Конфиденциальность и юридические аспекты

Никакой телеметрии, никакого сбора данных. Проверено (2026-08): единственное сетевое соединение, которое когда-либо открывает этот пакет, — это WebSocket к ROSBRIDGE_URL, который вы настраиваете — нет аналитики, нет звонков домой, нет отчётов о сбоях, нет скрытых HTTP-вызовов, и код не содержит логирования содержимого сообщений на диск. Встроенный mock-сервер привязывается только к 127.0.0.1. Данные робота, возвращаемые инструментами, передаются исключительно вашему MCP-клиенту (который пересылает их выбранной вами LLM — эта часть под вашим контролем, не нашим).

Соблюдение лицензий. Все зависимости времени выполнения и транзитивные зависимости имеют лицензии, совместимые с лицензией MIT этого проекта: прямые: fastmcp (Apache-2.0), websockets (BSD-3-Clause); ключевые транзитивные: mcp (MIT), pydantic (MIT), starlette (BSD-3-Clause), httpx (BSD-3-Clause), anyio (MIT), cryptography (Apache-2.0/BSD-3). Одна транзитивная зависимость, certifi, имеет лицензию MPL-2.0 — это уровень файла copyleft, который применяется только к модификациям собственных файлов certifi и совместим с использованием и распространением по MIT. В дереве зависимостей нет кода GPL/AGPL/проприетарного, и весь код в этом репозитории является оригинальной работой, написанной для этого проекта.

Часто задаваемые вопросы

Нужно ли устанавливать ROS там, где работает AI-клиент? Нет. Только Python 3.10+. ROS и rosbridge работают на роботе (или в Docker, или в симуляторе); этот сервер общается с ними через WebSocket.

Работает ли это с ROS 1? Протокол rosbridge v2 одинаков, поэтому базовые операции работают и с ROS 1 rosbridge_server — используйте имена типов ROS 1 (std_msgs/String). В CI тестируется только ROS 2.

Агент сообщает, что не может подключиться. Проверьте, что rosbridge запущен (ros2 launch rosbridge_server rosbridge_websocket_launch.xml), что ROSBRIDGE_URL указывает на правильный хост/порт, и что порт 9090 доступен (брандмауэр). Каждое руководство в docs/ содержит раздел по устранению неполадок.

Могу ли я попробовать без робота или симулятора? Да — python -m rosbridge_mcp.mock_server 9090 запускает поддельный rosbridge с предустановленными топиками, затем укажите ROSBRIDGE_URL на ws://localhost:9090.

Мои данные отправляются куда-либо? Сервер подключается только к настроенному ROSBRIDGE_URL. Данные топиков возвращаются вашему MCP клиенту, который передаёт их используемой LLM — обращайтесь с данными сенсоров соответственно.

План развития

Поэтапный план с целями, результатами и необходимыми ресурсами для каждого этапа: смотрите ROADMAP.md. Основные моменты: v0.2 клиент действий + TF + моментальные снимки камеры (сделано в v0.2.0), v0.3 HTTP транспорт + Docker образ + аутентификация/TLS rosbridge, v0.4 многороботные флоты + MCP ресурсы (URDF/карта), v1.0 стабильный API + официальная регистрация в MCP реестре + примеры с Gazebo/Isaac Sim.

Поддержка проекта

rosbridge-mcp создаётся и поддерживается одним человеком, неполный рабочий день, на ранней стадии. Всё, что существует сегодня, реально и протестировано: 11 инструментов, охватывающих топики, сервисы, ROS 2 действия, TF и моментальные снимки камеры; 43 автоматических теста, работающих в CI при каждом коммите; документация для 5 сценариев использования; режим безопасности «только чтение» с белым списком сервисов; и аудированный код без телеметрии.

Что необходимо для реализации плана развития, честно говоря:

• v0.3 (развёртывание и безопасность): несколько недель разработки неполный день, небольшое облачное VM или собственный раннер для сборки Docker образов и, что наиболее важно, рецензент, ориентированный на безопасность, для слоя аутентификации/TLS rosbridge.

• v0.4 (флоты): доступ к 2+ одновременно работающим роботам или экземплярам симулятора, а также обратная связь по дизайну от реальной робототехнической лаборатории (ищу академического или промышленного пилотного партнёра).

• v1.0 (стабильность и экосистема): постоянное время мейнтейнера (2 дня/неделю в течение квартала), одна RTX-класс GPU рабочая станция для валидации Isaac Sim — основной аппаратный запрос всего плана — и по желанию недорогой робот ($1–3k) для CI с аппаратурой в контуре.

Как вы можете помочь в порядке возрастания усилий:

1. Поставьте звезду репозиторию — видимость действительно помогает раннему проекту привлечь участников.

2. Попробуйте на своём роботе или симуляторе и откройте issue с вашей версией ROS + rosbridge — отчёты о совместимости — самый дешёвый способ сделать проект надёжным.

3. Внесите PR — docs/development.md объясняет структуру кода за 10 минут, и каждый пункт плана можно взять в работу.

4. Станьте спонсором или партнёром — если ваша лаборатория или компания может предоставить время симулятора, оборудование, GPU рабочую станцию или финансирование разработки, свяжитесь через github.com/hieutachi.

Связанные ресурсы

Если вы начинаете заниматься робототехникой, Robotics RL & UAV ebook — дополнительный учебный ресурс от автора, охватывающий обучение с подкреплением и робототехнику БПЛА.

Участие в разработке

Приветствуются любые вклады! Смотрите CONTRIBUTING.md и руководство по разработке. Пожалуйста, подписывайте свои коммиты (DCO).

Лицензия

MIT — смотрите LICENSE. Лицензии зависимостей разрешительные и совместимые: fastmcp (Apache-2.0), websockets (BSD-3-Clause). Нет зависимостей GPL/AGPL.

Краткое содержание на русском

rosbridge-mcp — это MCP сервер, который соединяет AI-агента (Claude Desktop, Cursor, VS Code...) с роботом, работающим на ROS 2, через протокол rosbridge (WebSocket + JSON). Устанавливать ROS на машине с AI-клиентом не требуется.

Документация разделена по сценариям — выберите подходящее руководство в папке docs/:

• Использование Claude Desktop — пошаговая настройка JSON на Windows/macOS/Linux

• Использование Cursor / VS Code — настройка mcp.json в редакторе

• Без робота — попробуйте с Docker (ros:humble + rosbridge) или TurtleBot3/Gazebo, или встроенным mock-сервером

• С настоящим роботом — чек-лист безопасности: сначала включите ROSBRIDGE_MCP_READONLY=true, прочитайте /odom, /scan, чтобы понять робота, затем откройте права на публикацию /cmd_vel

• Разработчику — архитектура кода, как добавить новый инструмент, запуск тестов с mock (без ROS)

11 инструментов: 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. Включите ROSBRIDGE_MCP_READONLY=true, чтобы заблокировать все операции записи (публикация, действия) при работе с реальным роботом — инструменты чтения (TF, камера, топики) продолжают работать нормально.

Сопутствующий учебный материал от автора: Robotics RL & UAV ebook — электронная книга по обучению с подкреплением (reinforcement learning) и робототехнике БПЛА.