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 для эффективной работы.

Related MCP server: MCP Terminal

Предпосылки

• 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 .