ROS2 MCP Server

ros2-mcp-сервер

ros2-mcp-server — это сервер на основе Python, который интегрирует протокол контекста модели (MCP) с ROS 2, позволяя помощникам ИИ управлять роботами через темы ROS 2. Он обрабатывает команды через FastMCP и работает как узел ROS 2, публикуя сообщения geometry_msgs/Twist в тему /cmd_vel для управления движением робота.

Эта реализация поддерживает такие команды, как «двигаться вперед со скоростью 0,2 м/с в течение 5 секунд и остановиться» с издателем /cmd_vel с именем pub_cmd_vel .

Функции

• Интеграция MCP : использует FastMCP для обработки команд от клиентов MCP (например, Claude).
• ROS 2 Native : работает как узел ROS 2, напрямую публикуя данные в /cmd_vel .
• Управление на основе времени : поддерживает команды движения на основе длительности (например, движение в течение определенного времени и остановка).
• Асинхронная обработка : объединяет asyncio FastMCP с циклом событий ROS 2 для эффективной работы.

Предпосылки

• ROS 2 : дистрибутив Humble установлен и загружен.
• Python : версия 3.10 (требуется для совместимости с ROS 2 Humble).
• uv : Менеджер пакетов Python для управления зависимостями.
• Зависимости :
  • rclpy : клиентская библиотека Python для ROS 2 (устанавливается вместе с ROS 2).
  • fastmcp : фреймворк FastMCP для реализации сервера MCP.
  • numpy : Требуется для типов сообщений ROS 2.

Установка

1. Клонировать репозиторий :
   git clone https://github.com/kakimochi/ros2-mcp-server.git cd ros2-mcp-server
2. Конфигурация версии Python : этот проект использует Python 3.10, как того требует ROS 2 Humble. Файл .python-version уже настроен:
   # .python-version content 3.10
3. Зависимости проекта : Файл pyproject.toml настроен с необходимыми зависимостями:
   # 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. Создать УФ-среду :
   uv venv --python /usr/bin/python3.10
5. Активируйте виртуальную среду :
   source .venv/bin/activate
   В начале командной строки вы увидите (.venv) , что означает, что виртуальная среда активна.
6. Установить зависимости :
   uv pip install -e .

Конфигурация сервера MCP

Чтобы использовать этот сервер с Claude или другими клиентами MCP, вам нужно настроить его как сервер MCP. Вот как это настроить:

Для рабочего стола Клода

1. Откройте настройки Claude Desktop и перейдите в раздел MCP-серверов.
2. Добавьте новый сервер MCP со следующей конфигурацией:
   "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" }
   Важно : замените /path/to/ros2-mcp-server на фактический путь к вашему репозиторию. Например, если вы клонировали репозиторий в /home/user/projects/ros2-mcp-server , вы должны использовать этот путь.
3. Сохраните конфигурацию и перезапустите Клода.

Для Клайна (расширение VSCode)

1. В VSCode откройте настройки расширения Cline, нажав на значок Cline на боковой панели.
2. Перейдите в раздел конфигурации серверов MCP.
3. Добавьте новый сервер MCP со следующей конфигурацией:
   "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" }
   Важно : замените /path/to/ros2-mcp-server на фактический путь к вашему репозиторию, как в примере Claude Desktop.
4. Вы можете мгновенно включать/выключать сервер и проверять соединение непосредственно из интерфейса настроек Cline MCP без необходимости перезапускать VSCode или перезагружать расширение.

Использование

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

1. Пример команды : попросите Клода переместить робота вперед со скоростью 0,2 м/с в течение 5 секунд:
   Please make the robot move forward at 0.2 m/s for 5 seconds.
2. Прямое использование инструмента : Вы также можете использовать инструмент move_robot напрямую:
   { "linear": [0.2, 0.0, 0.0], "angular": [0.0, 0.0, 0.0], "duration": 5.0 }
3. Мониторинг тем ROS 2 : проверьте вывод темы /cmd_vel :
   ros2 topic echo /cmd_vel

Тестирование

1. С помощью симулятора :
   • Запустите симулятор, совместимый с ROS 2 (например, Gazebo с TurtleBot3):
     export TURTLEBOT3_MODEL=burger ros2 launch turtlebot3_gazebo turtlebot3_world.launch.py
   • Используйте Клода для отправки команд движения.
   • Понаблюдайте за движением робота в Gazebo.
2. С настоящим роботом :
   • Убедитесь, что ваш робот правильно настроен для подписки на тему /cmd_vel .
   • Используйте Клода для отправки команд движения.
   • Робот должен двигаться согласно командам.
3. Ожидаемый результат :
   • Сервер регистрирует команды движения и команды остановки.
   • Клод получает ответ типа: "Successfully moved for 5.0 seconds and stopped" .

Поиск неисправностей

• Ошибки ведения журнала ROS 2 : если вы столкнулись с ошибками каталога ведения журнала, убедитесь, что переменная среды ROS_LOG_DIR установлена в доступном для записи каталоге (например, /tmp ).
• Несоответствие версий Python : убедитесь, что вы используете Python 3.10, так как ROS 2 Humble создан для этой версии.
• Ошибки подключения : если Клод сообщает об ошибках «Подключение закрыто», проверьте правильность конфигурации сервера MCP и установку всех зависимостей.

Структура каталога

Ограничения

• Отдельная тема : в настоящее время поддерживает /cmd_vel с сообщениями Twist . Расширьте ros2-mcp-server.py для других тем или служб.
• Базовые команды : В настоящее время поддерживает простые команды движения. Более сложные поведения потребуют дополнительной реализации.

Лицензия

Обратите внимание, что этот проект использует FastMCP , который лицензируется по Apache License 2.0. Условия этой лицензии также применяются к использованию компонентов FastMCP.

Благодарности

• Создано с использованием FastMCP и ROS 2 .