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

すべてのトピックとそのメッセージタイプを一覧表示します。パラメータはありません。

{"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 です。ツールがタイムアウトより長くハングすることはありません。

publish_message （変更あり）

トピックをアドバタイズし、1つの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 に渡すと、後でゴールを停止できます。ROS 2 アクションをサポートする rosbridge_suite のバージョンが必要です。古い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_static を短時間リッスンして、ロボットのTF（座標変換）ツリーのスナップショットを取得します。パラメータ：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

カメラトピックから1フレームを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 を返します）。4MBを超えるフレームは返されません。ツールはメタデータと圧縮トピックを提案するエラーで応答します。

get_connection_status

接続状態と読み取り専用モードを報告します。パラメータはありません。

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

会話例

あなた： ロボットは今、何を見ていますか？

エージェント： （list_topics を呼び出し、sensor_msgs/msg/LaserScan タイプの /scan を検出し、get_topic_snapshot を {"topic": "/scan", "count": 1} で呼び出す） レーザースキャナーは360の距離測定値を報告しています。最も近い障害物は、左約90度の方向に約0.4メートルです。真正面のスペースは少なくとも2.5メートル以上空いています。

あなた： わかりました、ゆっくり前進してください。

エージェント： （publish_message を {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}} で呼び出す） 0.1 m/s の前進速度コマンドをパブリッシュしました。停止するタイミングを教えてください。ゼロ速度をパブリッシュします。

ビジョンと身体化AIのために

読み取り専用ツールのうちの2つは、視覚言語モデルをロボットの物理的現実に根付かせるために特に存在します：

• get_camera_image は実際のカメラフレームをbase64として返します。視覚対応モデル（Claude、GPT-4o、またはVLAポリシーフロントエンド）は、何をすべきかを決定する前に文字通りロボットのカメラを通して見ることができます。

• get_tf_tree はモデルにロボットの空間的骨格を提供します。どのフレームが存在するか（map、odom、base_link、camera、gripper）と、それらが互いにどのように配置されているか。

get_topic_snapshot（LiDAR、オドメトリ、ジョイント状態）および 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）：このパッケージが開く唯一のネットワーク接続は、設定した ROSBRIDGE_URL へのWebSocketです。分析、ホームコールバック、クラッシュレポート、隠れたHTTP呼び出しはなく、コードにはメッセージ内容のディスクへのログ記録は含まれていません。バンドルされたモックサーバーは 127.0.0.1 にのみバインドします。ツールによって返されるロボットデータは、排他的にMCPクライアントに送られます（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）。1つの推移的依存関係である 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～3k）。

あなたができる支援（難易度順）：

1. リポジトリにスターを付ける — 可視性は初期プロジェクトに貢献者を引き寄せるのに本当に役立ちます。

2. 自分のロボットやシミュレーターで試す — ROSディストリビューションとrosbridgeバージョンを添えてIssueを開いてください。互換性レポートは、これを堅牢にするための最も安価な方法です。

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の依存関係はありません。

Tóm tắt tiếng Việt

rosbridge-mcp là một MCP server cầu nối giữa AI agent (Claude Desktop, Cursor, VS Code...) và robot chạy ROS 2 thông qua giao thức rosbridge (WebSocket + JSON). Không cần cài ROS trên máy chạy AI client.

Tài liệu được chia theo từng kịch bản — chọn đúng hướng dẫn cho bạn trong thư mục docs/:

• Dùng Claude Desktop — cấu hình JSON từng bước trên Windows/macOS/Linux

• Dùng Cursor / VS Code — cấu hình mcp.json trong editor

• Chưa có robot — chạy thử với Docker (ros:humble + rosbridge) hoặc TurtleBot3/Gazebo, hoặc mock server đi kèm

• Có robot thật — checklist an toàn: bật ROSBRIDGE_MCP_READONLY=true trước, đọc /odom, /scan để hiểu robot rồi mới mở quyền publish /cmd_vel

• Developer — kiến trúc code, cách thêm tool mới, chạy test với mock (không cần ROS)

11 tool: 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. Bật ROSBRIDGE_MCP_READONLY=true để chặn mọi thao tác ghi (publish, action) khi làm việc với robot thật — các tool đọc (TF, camera, topic) vẫn hoạt động bình thường.

Tài liệu học kèm theo của tác giả: Robotics RL & UAV ebook — ebook về học tăng cường (reinforcement learning) và robot UAV.