WiseVision ROS2 MCP Server

ROS2 MCP

ROS2 MCP は、AI エージェント（Claude、Cursor、Codex、その他すべての MCP クライアント）が稼働中のロボット上で ROS 2 のトピック、サービス、アクションを一覧表示、購読、パブリッシュ、呼び出しできる、オープンソース（MPL-2.0）の Model Context Protocol サーバーです。rclpy を介して ROS 2 と直接通信するため、rosbridge は不要で、ロボットを変更する必要もありません。トランスポートは stdio（デフォルト）、Streamable HTTP、SSE（MCP 仕様では非推奨）です。

すべてのツールは無料でオープンソースです。実機への導入を支援する商用サポートも利用できます。

⚡ クイックスタート（30秒、Docker）

必要なのは Docker と MCP クライアントです。イメージに ROS 2 が含まれているため、ROS 2 自体をインストールする必要はありません。

# Claude Code (use :humble for a ROS 2 Humble system). Read-only: the agent can look, not act.
claude mcp add ros2 -- docker run -i --rm -e ROS2_MCP_READONLY=1 wisevision/ros2_mcp:jazzy

その他の MCP クライアントでは、docker run -i --rm -e ROS2_MCP_READONLY=1 wisevision/ros2_mcp:jazzy を stdio コマンドとして実行します。その後、「ROS 2 のトピックを一覧表示して」と「/chatter からメッセージを3つ読み取って」と指示してください。

手元にロボットがない場合は、まずデモパブリッシャーを起動します。

docker run -d --name demo-robot ros:jazzy-ros-base bash -c \
  'source /opt/ros/jazzy/setup.bash && ros2 topic pub -r 2 /chatter std_msgs/msg/String "{data: hello from the robot}"'

uv を使う場合は、ROS 2 がインストールされ、環境がセットアップされたマシンで実行してください（サーバーには rclpy が必要です。Jazzy では 3.12 など、ディストリビューションに合った Python を使用してください）。

source /opt/ros/jazzy/setup.bash
uvx --python /usr/bin/python3 --from git+https://github.com/wise-vision/ros2_mcp mcp_ros_2_server

エージェントが動作を実行できるようにする場合に限り、-e ROS2_MCP_READONLY=1（または --read-only フラグ）を削除してください。セキュリティを参照してください。クライアント別のセットアップ（VS Code Copilot、Claude Desktop、Warp、Codex CLI、カスタムメッセージ）については、インストールガイドをご覧ください。ドキュメント：wisevision.tech/docs。

Docker 公式 MCP カタログの mcp/ros2（執筆時点で13,750回プル）は Docker がビルドしており、リリースへの追従が遅れています。最終更新日は 2026-02-04 で、読み取り専用モードより前のものです。wisevision/ros2_mcp はこのリポジトリの CI がビルドしてプッシュしており、上記のコマンドで使用するイメージです。

🧰 ツール

24 個のツールがあります。⚠ はロボットの状態を変更できるツールを示します。読み取り専用モードでは、これらのツールが除外されます。入力スキーマを含む完全な自動生成リファレンスは docs/generated/tools.md です（CI チェックにより、コードとの同期が保たれます）。

領域	ツール
検出	ros2_topic_list、ros2_service_list、ros2_list_actions、ros2_interface_list、ros2_get_message_fields（メッセージ型のフィールド名と型）
トピック	ros2_topic_subscribe、ros2_subscribe_multiple_topics（画像は PNG 形式で返されます）、⚠ ros2_topic_publish、⚠ ros2_publish_multiple_topics（頻度と継続時間を設定）
サービス	⚠ ros2_service_call
アクション	⚠ ros2_send_action_goal（必要に応じて結果を待機）、ros2_action_request_result、ros2_action_subscribe_feedback、ros2_action_subscribe_status、⚠ ros2_cancel_action_goal
認識	ros2_get_map_as_image（nav_msgs/OccupancyGrid を PNG に変換）、ros2_get_pointcloud_as_bev（sensor_msgs/PointCloud2 を鳥瞰図 PNG に変換）
履歴	ros2_get_messages_stored_in_influx_data_base（Rosbag2 に代わる InfluxDB ベースの WiseVision Data Black Box から過去のメッセージを取得）
ビューアアプリ	ros2_viewer_app、ros2_viewer_config、ros2_stream_start、ros2_stream_next、ros2_stream_next_image、ros2_stream_stop（Apps に対応する MCP クライアント向けのインタラクティブな画像／点群／プロットビューア。ストリームツールは、ビューアを表示できないクライアントにも対応します）

さらに、組み込みのプロンプト 4 種類、トピックの QoS 自動選択、ネストされたメッセージフィールド、カスタムメッセージ型にも対応しています（起動前にパッケージを source してください。詳しくはインストールガイドをご覧ください）。

🧭 対応する ROS 2 ディストリビューション

ディストリビューション	状況
Jazzy Jalisco（Ubuntu 24.04、Python 3.12）	対応しています。CI で ros:jazzy-ros-base を使用してテストを実行し、Docker イメージは wisevision/ros2_mcp:jazzy です。
Humble Hawksbill（Ubuntu 22.04、Python 3.10）	対応しています。CI で ros:humble-ros-base を使用してテストを実行し、Docker イメージは wisevision/ros2_mcp:humble です。
Iron、Kilted、Rolling	テストも配布も行っていません。ソースから動作する可能性はありますが、保証はありません。必要な場合はイシューを作成してください。

ROS 1 には対応していません（サーバーは rclpy を使用します）。Python 3.10 以降が必要です。

🆚 比較

ほかにもオープンソースの ROS MCP サーバーがあります。それぞれ異なるトレードオフがあるため、ニーズに応じて選んでください。以下の情報は、2026-10-14 に各プロジェクトの README、pyproject.toml、GitHub ページを確認したものです。

	ROS2 MCP（このリポジトリ）	robotmcp/ros-mcp-server	LCAS/ros2_mcp
ROS への接続方法	rclpy を使用し、ROS 2 グラフに直接接続します（ROS 2 の環境がセットアップされた場所、または Docker イメージ内で実行）	rosbridge WebSocket を使用します。MCP サーバーはロボットとは別のマシンでも実行できます	colcon ワークスペース内でビルドする ROS 2 パッケージ
ROS のバージョン	ROS 2 Humble、Jazzy	ROS 1、ROS 2	ROS 2 Humble、Iron、Jazzy（README による）
インストール	Docker イメージ wisevision/ros2_mcp、または git から uvx／uv	uvx ros-mcp（PyPI）	git clone、rosdep、colcon build。SSE エンドポイントを備えた Docker Compose
トランスポート	stdio、Streamable HTTP、SSE	stdio、http、streamable-http（--transport）	SSE エンドポイントをドキュメント化
読み取り専用モード	あり：変更を加えるツールは登録されず、テストで分類が強制されます	該当する切り替え機能はコード内に見つかりませんでした。ツールには MCP の readOnlyHint アノテーションが付いています	README には観測機能のみが記載されています
パブリッシュ／サービス／アクション	あり。ゴール、結果、フィードバック、ステータス、キャンセルを含みます	あり（トピック、サービス、アクションのツール）	README に記載なし
ノードとパラメーター	専用ツールはまだありません	あり（ノードとパラメーターのツール）	ノード一覧表示
画像とマップ	画像トピックを PNG で取得、占有グリッドマップ、点群の俯瞰表示	画像ツール	VLM 分析用の画像取得
ライセンス	MPL-2.0	Apache-2.0	Apache-2.0
GitHub スター数	90	1,493	9

別のものを選ぶべきケース：ROS 1、ノードまたはパラメーターのツールが必要な場合、あるいは rosbridge のみをロボット上で公開し、MCP サーバーをロボットの外部で実行したい場合は、robotmcp/ros-mcp-server を使用してください。あらゆる点で優れているとは主張していません。私たちが提供するのは、ネイティブな rclpy アクセス（エージェントと DDS の間にブリッジプロセスが不要）、フェイルクローズ方式の読み取り専用モード（明示的に読み取り専用としてレビューされた場合に限り、そのモードでツールが登録され、新しいツールが未分類だとテストが失敗します）、PNG で返される画像、マップ、点群、アクションの完全なライフサイクル（ゴール、結果、フィードバック、ステータス、キャンセル）、そして必要に応じた商用サポートです。ここに誤りや古い情報があれば、issue を作成してください。修正します。

🗺️ ロードマップ（提案段階であり、確定ではありません）

ROS2 MCP に現在含まれていない、ユーザーから要望のある機能です。日程は未定です。投票したり、実装費用を負担したりするには、issue または Discussion を作成してください。

• パラメーターツール：ノードパラメーターの取得／設定／一覧表示。
• TF ツール：変換の検索とフレームツリー。
• Streamable HTTP の認証（ベアラートークン、または手順を記載したリバースプロキシの設定例）。トランスポート自体は #55 にあります。認証が追加されるまでは、ループバックまたはプライベートネットワーク上で使用してください。
• ノードツール（ノード一覧、ノード情報）、Nav2 固有のヘルパー、PyPI パッケージ、ROS 1（予定なし）。

🤖 AI エージェント向け

このサーバーを使用するエージェント（またはエージェントを構築している方）は、次の点にご注意ください。

• 操作する前に、まず情報を確認してください。 公開、サービス呼び出し、アクションゴールの送信を行う前に、ros2_topic_list、ros2_service_list、ros2_list_actions、ros2_interface_listを呼び出し、続けて該当するメッセージ型に対してros2_get_message_fieldsを呼び出してください。フィールド名を推測しないでください。
• 読み取り専用を優先してください。 ros2_topic_publish、ros2_service_call、ros2_send_action_goalがlist_toolsにない場合、オペレーターはサーバーを読み取り専用モードで起動しています。回避を試みないでください。
• 状態を変更するツールは実際の機械を動かします。 ⚠ツールを呼び出す前に、人間に意図を確認してください。小さな値と短い時間から始め、ros2_cancel_action_goalも念頭に置いてください。
• コンテナーの起動直後は、グラフが不完全な場合があります（DDS検出中）。予想していたトピックが見つからない場合は、存在しないと判断する前に一度再試行してください。DDS検出のウォームアップを参照してください。
• 機械可読なリファレンス： docs/generated/tools.json（すべてのツールとその入力スキーマ）、server.json（MCP レジストリマニフェスト）、AGENTS.md（リポジトリの構成、ビルド、テスト、ツールの追加方法）、wisevision.tech/llms.txt。

🏢 商用サポートと統合

ROS2 MCPはMPL-2.0に基づくフリーソフトウェアです。許可を得ることなく商用製品で使用できます。このセクションの内容によって、その条件が変わることはありません。

実際のロボットやロボット群に導入する際に、公開されている課題トラッカー以外のサポートをお求めの場合、メンテナーであるWiseVisionが次のような支援を提供できます。

• 統合サポート：お使いのスタック、メッセージ型、QoSの制約に合わせてサーバーを稼働させるための支援。
• カスタムツールとプロンプト：組み込みのトピック、サービス、アクション以外に、お客様独自のインターフェースに対応するハンドラー。
• 優先修正：導入を妨げる不具合を、バックログではなくスケジュールに沿って対応します。

お問い合わせ方法： wisevision.tech/contactのフォーム（ROS2 MCP on a real fleetを選択）をご利用いただくか、[email protected]までメールでご連絡ください。まず、ロボットの種類、スタック、阻害要因など、問題についてお知らせください。プロジェクトごとに範囲を定めて見積もります。料金表はありませんので、お問い合わせください。他のユーザーにも役立つ質問は、ディスカッションまたはイシューにお寄せください。

まず実データで試してみたい方は、フォークリフトのrosbagデモで倉庫のフォークリフトの記録を再生し、約10分で3つのMCP呼び出しを順に確認できます。

⚙️ インストール

手順に沿って進められるインストールガイドをご覧ください。

• 🧩 Visual Studio Code Copilotへのインストール
• 🤖 Claude Desktopへのインストール
• 💻 Warpへのインストール
• 🐳 Dockerイメージをローカルでビルド

🔒 セキュリティ：読み取り専用モード

実際のロボットに接続されたエージェントは、ロボットを動かすことができます。エージェントに観察のみを許可し、操作はさせないよう、サーバーを読み取り専用モードで起動してください。

ROS2_MCP_READONLY=1 uv run mcp_ros_2_server      # env var
uv run mcp_ros_2_server --read-only              # or CLI flag
docker run -i --rm -e ROS2_MCP_READONLY=1 mcp/ros2

読み取り専用モードでは、ロボットの状態を変更するツールは登録されません。list_toolsにも表示されず、呼び出すとUnknown toolエラーが返されます。非表示になるツールは次のとおりです。 ros2_topic_publish、ros2_publish_multiple_topics、ros2_service_call、ros2_send_action_goal、ros2_cancel_action_goal。 読み取り専用モードはフェイルクローズ方式です。読み取り専用として明示的に確認されたツール（server/tool_safety.pyに記載）のみが登録され、新しいツールが分類されずに追加された場合はテストが失敗します。 任意のサービスに副作用があるかどうかをサーバーが判断できないため、ros2_service_callは非表示になります。

🌐 Streamable HTTP（リモート／複数クライアント）

stdio はデフォルトであり、ネットワークは不要です。複数のクライアント、または別のマシン上のクライアントにサービスを提供するには、Streamable HTTP を使用します。これは現在の MCP 仕様で定義されているトランスポートです（以前の sse トランスポートは仕様で非推奨となっており、既存のクライアント向けにのみ維持されています）。

uv run mcp_ros_2_server --transport streamable-http          # http://127.0.0.1:8123/mcp
claude mcp add --transport http ros2 http://127.0.0.1:8123/mcp   # Claude Code; other clients: use the URL

Docker（ポートをループバックのみに公開）：

docker run --rm -p 127.0.0.1:8123:8123 \
  -e ROS2_MCP_TRANSPORT=streamable-http -e ROS2_MCP_HOST=0.0.0.0 -e ROS2_MCP_READONLY=1 \
  wisevision/ros2_mcp:jazzy                                 # http://127.0.0.1:8123/mcp

ROS2_MCP_HOST=0.0.0.0 はコンテナ内で必要です（ループバックへのバインドでは -p 経由で到達できません）。-p の 127.0.0.1: によって、ネットワーク上には公開されません。最初のツール呼び出しでトピックが何も表示されない場合、DDS の検出がコンテナの境界を越えていません。Linux では通常、--network host を指定し（その場合は -p と ROS2_MCP_HOST を削除します）、解決しますが、DDS とネットワークの設定によって異なります。

オプション	環境変数	デフォルト
--transport	ROS2_MCP_TRANSPORT	stdio	stdio、streamable-http、sse
--host	ROS2_MCP_HOST	127.0.0.1	コンテナ内では 0.0.0.0
--port	ROS2_MCP_PORT	8123
--allowed-host HOST[:PORT]	ROS2_MCP_ALLOWED_HOSTS	ループバックへのバインド時は localhost のみ	許可する Host ヘッダー（DNS リバインディング対策）；複数指定可能／カンマ区切り；* は任意のポートに一致
--stateless、--json-response		無効	クライアントごとのセッション状態を保持せず、イベントストリームの代わりに通常の JSON を返します

⚠️ 認証機能はありません。 ポートに接続できる人は誰でも、トピックへの公開を含むすべてのツールを使用できます。ループバックまたはプライベートネットワーク内に限定し、より広い範囲に公開する場合は、認証を行うリバースプロキシを前段に配置してください。また、読み取り専用モードの利用も検討してください。サーバーはループバック以外のアドレスにバインドすると警告を表示します。

🧭 DDS 検出のウォームアップ（Docker）

コンテナの起動直後に最初のツール呼び出しでトピック／サービスの一覧が不完全な場合、DDS の検出がまだ進行中の可能性があります。 サーバーはコンテナ環境で最初のツール呼び出し時に一度だけウォームアップを行います。次の設定で調整できます。

• MCP_ROS_DISCOVERY_STABLE_SEC（デフォルト：1.0）
• MCP_ROS_DISCOVERY_TIMEOUT_SEC（デフォルト：5.0）
• MCP_ROS_DISCOVERY_WARMUP=false で無効化

🤖 プロンプト

📘 カスタムプロンプトを作成したいですか？こちらのガイドをご覧ください

📊 base.ros2-topic-echo-and-analyze

ROS2 トピックをサブスクライブし、指定した時間だけメッセージを収集して、収集したデータを統計的に分析します。

➡️ 利用可能なトピックが1つだけの場合は、自動検出できます。メッセージの頻度、件数、数値フィールドの統計を分析します。

🔄 base.ros2-topic-relay

ROS2 トピックを1つサブスクライブし、任意の変換を適用して、メッセージを別のトピックに再公開します。

➡️ そのまま中継する機能、レート制限、変更に基づくフィルタリングに対応しています。

🏥 base.ros2-node-health-check

想定される ROS2 トピックとサービスが利用可能で、正しく機能しているかを確認します。公開レートの監視も任意で行えます。

➡️ ステータス表示と推奨事項を含む、包括的なヘルスレポートを提供します。

🔍 base.ros2-topic-diff-monitor

2つの ROS2 トピックを比較し、メッセージの違いをフィールドごとに詳しく分析して報告します。

➡️ 生のセンサーデータとフィルター処理／処理済みデータの比較や、トピックの同期確認に役立ちます。

ROS2 MCP には、追加のプロンプトを提供するプロンプト拡張機能もあります：こちらをご覧ください

💡 プロンプトが何かわかりませんか？MCP 仕様はこちら。

注： カスタム（デフォルト以外の）型を使用するサービスを呼び出すには、サーバーを起動する前に、その型を定義するパッケージを source してください。

🎬 デモ

🚀 プロンプトを使用したドローンミッション

🌍 実世界の例

シミュレーションで試してみませんか？Gazebo ドローンデモをご覧ください。

🐞 デバッグ

MCP サーバーは stdio 経由で動作するため、デバッグは難しい場合があります。最適なデバッグ体験を得るために、MCP Inspector の使用を強くおすすめします。

次のコマンドを使って、 npm 経由で MCP Inspector を起動できます。

npx @modelcontextprotocol/inspector uv --directory /path/to/ros2_mcp run mcp_ros_2_server

起動すると、Inspector に URL が表示されます。その URL にブラウザーからアクセスして、デバッグを開始できます。

🤝 コントリビューション

コントリビューションを歓迎します。未解決の Issue を確認するか、プルリクエストを作成するか、アイデアについて話し合うために Discord にお越しください。開発環境のセットアップとテストについては、AGENTS.md をご覧ください。参加することで、行動規範に同意したものとみなされます。

📚 開発の背景

AI 支援による ROS 2 開発を迅速かつ確実に行えるよう、このサーバーを開発しました。私たちは内部で、エージェントが定型コードや不安定なネットワーク通信に煩わされることなく、メッセージ型を見つけ、トピックをパブリッシュ／サブスクライブし、サービスを呼び出せる簡単な方法を必要としていました。そこで、以下のような中核となる設計目標を定めました。

• エージェントがあらゆるコードを作成・テストできるよう、ネストされたフィールドを含むすべての ROS 2 メッセージ型を扱う
• トピックの pub/sub とサービス呼び出しを統合し、動作をエンドツーエンドで検証する
• VS Code の GitHub Copilot やその他の MCP クライアントとシームレスに連携する
• シンプルな stdio トランスポートを使用し、ネットワークの複雑さを避ける

自分たちで実際に使い込んだ後、より広い ROS 2 コミュニティが AI を活用してより迅速に開発できるよう、このプロジェクトをオープンソース化しました（MPL-2.0）。現在では、開発だけでなく、ロボットの制御、QoS の実験、ライブデータやロボット／スウォームの状態の分析にも役立っています。このプロジェクトは積極的にメンテナンスされており、ユーザーからのフィードバックに基づいて、機能や改善が定期的に提供されています。このプロジェクトが役に立った場合は、Discussions でユースケースを共有してください。