rosbridge-mcp

rosbridge-mcp는 Model Context Protocol 서버로, AI 에이전트(Claude Desktop, Cursor, VS Code 및 기타 MCP 클라이언트)를 표준 rosbridge v2 프로토콜(WebSocket + JSON)을 통해 ROS 2를 실행하는 로봇에 연결합니다. 로봇 또는 ROS 머신에서 rosbridge_server를 실행합니다. 이 MCP 서버는 네트워크를 통해 여기에 연결되며, AI가 토픽을 관찰하고, ROS 그래프와 TF 트리를 검사하고, 로봇의 카메라를 통해 보고, 메시지를 게시하고, 서비스를 호출하고, ROS 2 액션을 구동할 수 있도록 하는 11개의 도구를 제공합니다. AI 클라이언트를 실행하는 머신에 ROS 설치가 필요하지 않습니다.

아키텍처

+--------------------+   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을 반환합니다. 메시지 및 인자 페이로드는 rosbridge에서 사용하는 ROS 메시지의 동일한 JSON 표현을 사용합니다 (필드 이름은 .msg/.srv/.action 정의와 일치).

list_topics n

모든 토과 해당 메시지 유형을 리스트합니다. 파라미터 없음.

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

모든 사용 가한 서비스를 리스트합니다. 파라미터 없음.

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

get_topic_snapshot n

토픽에 구독하고, 메시지를 수집하고, 구독을 취소합니다. 파라미터: 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 (변경) n

토을 광고하고 하나의 JSON 메시지를 게시합니다. 파라미터: topic, msg_type (전체 ROS 2 유형, 예: geometry_msgs/ms/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 (변경) n

모든 ROS 서비스를 호출합니다. 파라미터: service (필수), args (JSON 객체, 기본값 {}), timeout 초 (기본값 10.0). n 입력: {"service": "/rosapi/topic_type", "args": {"topic": "/scan"}} n GXP9 n 실패 시 도구는 {"success": false, "error": "..."}을 반환하며 예외를 발생시키지 않습니다. n

send_action_goal (변경) n

ROS 2 액션 서버(네비게이션, 암 모션 등)에 목표를 보냅니다. 파라미터: action_name, action_type (전체 유형은 /action/ 포함, 예: nav2_msgs/ction/NavigateToose), goal (JSON 객체, 기본값 {}), timeout 초 (기본값 30, 최대 120으로 제한), wait_for_result (기본값 true). n 입력: {"action_name": "/fibonacci", "action_type": "test_msgs/action/Fibonacci", "goal": {"order": 5}} n GXP10 n wait_for_result: false인 경우 도구는 즉시 {"goal_id": ..., "result_pending": true}를 반환합니다 — 나중에 목표를 중지하려면 해당 goal_id를 cancel_action_goal에 전달하세요. ROS 2 액션 지원이 포함된 rosbridge_suite 버전이 필요하며, 오래된 rosbridge에 대해 도구는 대신 업그레이드를 권장하는 오류를 반환하고 중단되지 않습니다.

cancel_action_goal (변경) n

이전에 보낸 액션 목표를 취소합니다. 파라미터: action_name, goal_id (send_action_goal에서 가져옴).

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

get_tf_tree n

/ff와 tf_static에 잠간 청취하여 로의 T (좌표 변환) 트리 스냅샷을 가져옵니다. 파라미터: 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/ms/CompressedImage 토 선호, 예: /camera/image_raw/compressed), timeout 초 (기본값 5.0, 최대 30으로 제한).

출력: {"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234} (원시 Image 토은 추가로 width/height/encoding 반환). 4 MB 초과 프레임은 반환되지 않으며 도구는 메타데이터와 압축 토을 제안하는 오류로 응답합니다.

get_connection_status n

연결 상테와 읽기 전용 모도를 보고합니다. 파라미터 없음.

GXP12 n

예시 대화

당신: 로이 지금 무었을 보고 있나요?

에이전트: (list_topics 호출, sensor_msgs/msg/LaserScan 유형의 /scan 찾음, 그 다음 get_topic_snapshot을 {"topic": "/scan", "count": 1}로 호출) n> 레이저 스너는 360개 범위 읽기을 보고합니다. 가장 가까운 장에물은 왼른 쪽 약 90°에서 약 0.4 m 떨어져 있습다. 정면 쪽은 적어도 2.5 m 동안 막혀 있습다.

당신: 좋아요, 잠시 동안 천천히 앞으로 주행하세요.

에이전트: (publish_message를 {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}로 호출) 0.1 m/s 전진 속도 명령을 게시했습니다. 중단하고 싶을 때 알려주시면 속도를 0으로 게시하겠습니다.

비전 및 임베디드 AI를 위한

두 가지 읽기 전용 도구는 비전-언어 모델을 로봇의 물리적 현실에 근거시키기 위해 특별히 존재합니다:

• **get_camera_image**는 실제 카메라 프레임을 base64로 반환합니다 — 시각 기능이 있는 모델(Claude, GPT-4o, 또는 VLA 정책 프론트엔드)은 결정을 내리기 전에 문자 그대로 로봇의 카메라를 통해 볼 수 있습니다.

• **get_tf_tree**는 모델에 로봇의 공간적 골격을 제공합니다 — 어떤 프레임(map, odom, base_link, camera, gripper)이 존재하고 서로 어떻게 배치되어 있는지.

get_topic_snapshot(라이다, 주행 거리, 조인트 상태) 및 send_action_goal(네비게이션, 조작)과 결합되면, 모델 측에 ROS 설치 없이, 일반 WebSocket을 통해 비전 및 동작 에이전트가 필요로 하는 관찰 → 추론 → 수행 을 커버합니다. 두 지각 도구 모두 읽기 전용 모드에서 작업하므로 "보고 만지지 않는" 에이전트를 안전하게 실행할 수 있습다.

구정

안전

언어 모델이 물리적 로봇에 /cmd_vel을 게시하도록 하는 것음 실체적 위험입니다. ROSBRIDGE_MCP_READONLY=true로 설정하여 읽기 전용 모드로 실행하세요: publish_message, send_action_goal, cancel_action_goal이 거부되며, call_service는 알려진 읽기 전용 /rosapi 인트로스펙션 서비스(토픽, 노드, 서비스, 유형, get_param, get_time, ...)의 고정된 허용 목록만 허용합니다 — 목록에 없는 항목(알려지지 않은 향후 /rosapi 서비스 포함)은 거부됩니다. 읽기 전용 지각 도구(get_topic_snapshot, get_tf_tree, get_camera_image)는 계속 작동합니다. 실제 하드웨어에서는 읽기 전용 모드로 시작하는 것을 강력히 권장합니다 — 전체 실제 로봇 안전 점검 목록 및 SECURITY.md의 배포 보안 모델을 참조하세요. n

개인정보 보호 및 법적 고지

텔레메트리 없음, 데이터 수집 없음. 감사 완료 (2026-08): 이 패키지가 여는 유일한 네트워크 연결은 사용자가 구성한 ROSBRIDGE_URL에 대한 WebSocket입니다 — 분석, 전화 홈, 크래시 보고, 숨겨진 HTTP 호출이 없으며, 코드에는 메시지 내용을 디스크에 로깅하는 내용이 전혀 없습니다. 번들된 모의 서버는 127.0.0.1에만 바인딩됩니다. 도구가 반환하는 로봇 데이터는 전적으로 MCP 클라이언트로 전송되며(이 데이터는 선택한 LLM으로 전홥됨 — 그 부문은 귀하의 통제 하에 있씁, 당신의 통제 아님). n 라이선스 준수. 모든 런타임 및 전이 의존성은 이 프젝트의 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입니다 — 파일 수준의 카피레프트로 certifi 자체 파일의 수정에만 적용되며 MIT 사용 및 재배포와 호환됩니다. 의존성 트리에 GPL/AGPL/독점 코드가 전혀 없으며, 이 저장소의 모든 코드는 이 프로젝트를 위해 작성된 독창적인 작업입니다.

FAQ

AI 클라이언트가 실향되곳 곳에 ROS가 설치되어 야 하나요? 아니오. 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 이미지 + rosbridge 인증/TLS, v0.4 다중 로봇 플릿 + MCP 리소스(URDF/맵), v1.0 안정적인 API + 공식 MCP 레지스트리 등록 + Gazebo/Isaac Sim 예제.

이 프로젝트 지원하기

rosbridge-mcp는 한 사람이 초기 단계에서 파트타임으로 구축하고 유지 관리합니다. 현재 존재하는 것은 실제로 작동하며 테스트되었습니다: 11개의 도구 — 토픽, 서비스, ROS 2 액션, TF, 카메라 스냅샷 포함; 43개의 자동화된 테스트가 모든 커밋마다 CI에서 실행됨; 5가지 사용자 경로에 대한 시나리오별 문서; 읽기 전용 안전 모드와 서비스 허용 목록; 감사된 제로 텔레메트리 코드베이스.

로드맵이 현실이 되기 위해 필요한 것, 솔직하게 말씀드리면:

• v0.3 (배포 및 보안): 파트타임 개발 주, Docker 이미지 빌드를 위한 소규모 클라우드 VM 또는 자체 호스팅 러너, 그리고 가장 중요한 — rosbridge 인증/TLS 계층에 대한 보안 중심 검토자.

• v0.4 (플릿): 2대 이상의 동시 실행 로봇 또는 시뮬레이터 인스턴스에 대한 액세스, 그리고 실제 로봇 연구소의 설계 피드백(학술 또는 산업 파일럿 파트너 찾고 있음).

• v1.0 (안정성 및 생태계): 지속적인 유지 관리자 시간(분기당 주 2일 정도), Isaac Sim 검증을 위한 RTX급 GPU 워크스테이션 1대 — 전체 로드맵의 주요 하드웨어 요청 — 그리고 선택적으로 하드웨어 인더루프 CI를 위한 저가형 로봇(약 1~3천 달러).

도움을 주실 수 있는 방법(노력 순서대로):

1. 저장소에 별표를 눌러주세요 — 가시성은 초기 프로젝트에 기여자를 얻는 데 실제로 도움이 됩니다.

2. 로봇이나 시뮬레이터에서 시도해보고 ROS 배포판 + rosbridge 버전과 함께 이슈를 열어주세요 — 호환성 보고는 이 프로젝트를 견고하게 만드는 가장 저렴한 방법입니다.

3. PR을 기여해주세요 — docs/development.md는 10분 안에 코드베이스를 설명하며, 모든 로드맵 항목은 클레임 가능합니다.

4. 후원 또는 파트너십 — 연구소나 회사에서 시뮬레이터 시간, 하드웨어, GPU 워크스테이션, 또는 개발 자금을 제공할 수 있다면 github.com/hieutachi를 통해 연락주세요.

관련 자료

로봇 공학에 입문하는 경우, Robotics RL & UAV ebook은 저자가 작성한 강화 학습 및 UAV 로봇 공학을 다루는 동반 학습 자료입니다.

기여

기여는 환영합니다! CONTRIBUTING.md 및 개발 가이드를 참조하세요. 커밋에 서명(DCO)해 주세요.

라이선스

MIT — LICENSE 참조. 종속성 라이선스는 허용적이며 호환 가능합니다: fastmcp (Apache-2.0), websockets (BSD-3-Clause). GPL/AGPL 종속성 없음.

베트남어 요약

rosbridge-mcp는 AI 에이전트(Claude Desktop, Cursor, VS Code 등)와 rosbridge 프로토콜(WebSocket + JSON)을 통해 ROS 2를 실행하는 로봇을 연결하는 MCP 서버입니다. AI 클라이언트를 실행하는 머신에 ROS를 설치할 필요가 없습니다.

문서는 시나리오별로 나뉘어 있습니다 — docs/ 디렉토리에서 자신에게 맞는 가이드를 선택하세요:

• Claude Desktop 사용 — Windows/macOS/Linux에서 단계별 JSON 구성

• Cursor / VS Code 사용 — 편집기에서 mcp.json 구성

• 로봇 없음 — Docker(ros:humble + rosbridge) 또는 TurtleBot3/Gazebo, 또는 포함된 모의 서버로 시험 실행

• 실제 로봇 있음 — 안전 체크리스트: 먼저 ROSBRIDGE_MCP_READONLY=true를 활성화하고, /odom, /scan을 읽어 로봇을 이해한 후에 /cmd_vel 발행 권한을 여세요

• 개발자 — 코드 아키텍처, 새 도구 추가 방법, 모의로 테스트 실행(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 — 강화 학습 및 UAV 로봇 공학에 관한 전자책.