ROS2 MCP Server

ros2-mcp-서버

ros2-mcp-server 는 ROS 2와 모델 컨텍스트 프로토콜(MCP)을 통합하는 Python 기반 서버로, AI 어시스턴트가 ROS 2 토픽을 통해 로봇을 제어할 수 있도록 합니다. FastMCP를 통해 명령을 처리하고 ROS 2 노드로 실행되어 /cmd_vel 토픽에 geometry_msgs/Twist 메시지를 게시하여 로봇의 움직임을 제어합니다.

이 구현은 pub_cmd_vel 이라는 이름의 /cmd_vel 게시자를 사용하여 "5초 동안 0.2m/s로 전진하고 멈춤"과 같은 명령을 지원합니다.

특징

• MCP 통합 : FastMCP를 사용하여 MCP 클라이언트(예: Claude)의 명령을 처리합니다.
• ROS 2 네이티브 : ROS 2 노드로 작동하며 /cmd_vel 에 직접 게시합니다.
• 시간 기반 제어 : 지속 시간 기반 이동 명령(예: 지정된 시간 동안 이동하고 중지)을 지원합니다.
• 비동기 처리 : 효율적인 작업을 위해 FastMCP의 asyncio 와 ROS 2의 이벤트 루프를 결합합니다.

필수 조건

• ROS 2 : Humble Distribution 설치 및 소싱.
• Python : 버전 3.10(ROS 2 Humble과의 호환성을 위해 필요).
• uv : 종속성 관리를 위한 Python 패키지 관리자.
• 종속성 :
  • rclpy : ROS 2 Python 클라이언트 라이브러리(ROS 2와 함께 설치됨).
  • fastmcp : MCP 서버 구현을 위한 FastMCP 프레임워크.
  • numpy : ROS 2 메시지 유형에 필요합니다.

설치

1. 저장소 복제 :지엑스피1
2. Python 버전 구성 : 이 프로젝트는 ROS 2 Humble에 필요한 Python 3.10을 사용합니다. .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 환경 생성 :
   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. 구성을 저장하고 Claude를 다시 시작합니다.

Cline(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" }
   중요 : Claude Desktop 예시처럼 /path/to/ros2-mcp-server 저장소의 실제 경로로 바꾸세요.
4. VSCode를 다시 시작하거나 확장 프로그램을 다시 로드하지 않고도 Cline MCP 설정 인터페이스에서 바로 서버를 켜거나 끌 수 있고 연결을 확인할 수 있습니다.

용법

MCP 서버가 구성되면 Claude를 사용하여 로봇에 명령을 보낼 수 있습니다.

1. 예제 명령 : Claude에게 로봇을 5초 동안 0.2m/s의 속도로 전진시키라고 요청합니다.
   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 호환 시뮬레이터(예: TurtleBot3가 포함된 Gazebo)를 실행합니다.
     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 버전 불일치 : ROS 2 Humble은 이 버전에 맞춰 빌드되었으므로 Python 3.10을 사용하고 있는지 확인하세요.
• 연결 오류 : Claude가 "연결 닫힘" 오류를 보고하는 경우 MCP 서버 구성이 올바르고 모든 종속성이 설치되었는지 확인하세요.

디렉토리 구조

제한 사항

• 단일 토픽 : 현재 Twist 메시지와 함께 /cmd_vel 지원합니다. 다른 토픽이나 서비스를 위해 ros2-mcp-server.py 확장합니다.
• 기본 명령 : 현재 간단한 이동 명령을 지원합니다. 더 복잡한 동작은 추가 구현이 필요합니다.

특허

이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여된 FastMCP를 사용합니다. 해당 라이선스 조건은 FastMCP 구성 요소 사용에도 적용됩니다.

감사의 말

• FastMCP 와 ROS 2 로 구축되었습니다.