ros-mcp

ROS 2 MCP Server

GitHub Copilot やその他の AI エージェントが ROS 2 システムと連携できるようにする、ROS 2 用の Model Context Protocol（MCP）サーバーです。このサーバーは、ROS 2 のノード、トピック、サービス、TF2 フレームを監視、デバッグ、管理するためのツールを提供します。

クイックスタート

.vscode/mcp.json に以下を追加します

{
  "servers": {
    "ros": {
      "command": "npx",
      "args": ["ros-mcp"]
    }
  }
}

VS Code Copilot のツールでサーバーが選択されていることを確認してください

これで準備完了です！ 「List active ros topics」を試して動作を確認してみてください。

機能

ノード管理

• list_ros_nodes: 実行中のすべての ROS 2 ノードを詳細情報とともに一覧表示します
• get_node_connections: ノードがパブリッシュまたはサブスクライブしているすべてのトピックを表示します
• get_node_parameters: 特定のノードのパラメーターを一覧表示します
• set_node_parameter: 実行時にノードのパラメーターを変更します
• run_ros_node: パッケージから ROS 2 ノードを起動します
• run_ros_launch: launch ファイルを実行します

トピックの監視

• list_ros_topics: 詳細な型情報を任意で指定して、利用可能なすべてのトピックを一覧表示します
• get_topic_info: 特定のトピックの詳細情報を取得します
• monitor_topic: トピックをサブスクライブし、指定した時間メッセージを収集します（待機機能を備えた観察用ツール）
• publish_to_topic: トピックにメッセージをパブリッシュします

サービス管理

• list_ros_services: 利用可能なすべてのサービスを一覧表示します
• call_service: 任意のパラメーターを指定してサービスを呼び出します

TF2 フレームの監視

• monitor_tf2_frames: TF2 の変換フレームと関係を監視します（静的変換と動的変換を含みます）

システムの可視化とデバッグ

• generate_ros_graph: ノードとトピック間の接続を示す依存関係グラフを生成します（テキスト形式と Graphviz DOT 形式の両方に対応）
• check_ros_system_status: システム全体の健全性、デーモンの状態、ノード／トピック／サービスの数を確認します

インストール

前提条件

• ROS 2（Humble 以降でテスト済み）
• Node.js 18+
• npm または yarn

手動セットアップ

# Clone or navigate to the repository
cd /path/to/ROS-MCP

# Install dependencies
npm install

# Build the TypeScript
npm run build

WSL では、nvm の node をデフォルトの node パスにリンクする必要がある場合があります

sudo ln -s ~/.nvm/versions/node/v24.11.0/bin/node /usr/local/bin/node sudo ln -s ~/.nvm/versions/node/v24.11.0/bin/npm /usr/local/bin/npm

使い方

サーバーの実行

# Direct execution (recommended for MCP integration)
npm start

# Development with ts-node
npm run dev

GitHub Copilot を使う

GitHub Copilot の設定で MCP サーバーを構成します。

{
  "servers": {
    "ros": {
      "command": "node",
      "args": ["/path/to/ROS-MCP/build/index.js"]
    }
  }
}

ツールの詳細

観察用ツール（待機機能あり）

一部のツールは、エージェントが待機して観察できるよう、時間をかけてデータを収集するように設計されています。

• monitor_topic: 1〜30 秒間待機し、トピックからメッセージを収集します。メッセージ数の上限をカスタマイズできます。次の用途に最適です。

  • センサーデータのストリームを観察する
  • トピックのパブリッシュパターンを検証する
  • メッセージのスループットをデバッグする

• monitor_tf2_frames: 指定した時間（1〜30 秒間）、TF2 フレームの変換を観察します

ツールの例

トピックを監視する

Tool: monitor_topic
Parameters:
  - topic_name: "/sensor_msgs/LaserScan"
  - duration_seconds: 5
  - message_count: 10

5 秒間に LaserScan トピックから最大 10 件のメッセージを収集します。

ノードグラフを生成する

Tool: generate_ros_graph
Parameters:
  - output_format: "text" (or "dot" for Graphviz)

ノードとトピックの接続状況を視覚的に表現して返します。

システムの健全性を監視する

Tool: check_ros_system_status
Parameters:
  - include_diagnostics: true

デーモンの健全性、アクティブなノード、サービスなど、システムの包括的な状態を提供します。

アーキテクチャ

このサーバーは以下を使用して構築されています。

• @modelcontextprotocol/sdk: エージェントとの通信に使用する MCP フレームワーク
• Zod: 型安全なパラメーター検証
• Node.js Child Process: ROS 2 CLI ツールのコマンド実行

動作の仕組み

1. コマンドの実行：各ツールは対応する ros2 CLI コマンドを実行します
2. 出力の解析：結果は解析され、エージェントが利用できる形式に整えられます
3. タイムアウト処理：観測ツールは設定可能なタイムアウトを使用してデータを収集します
4. エラー処理：失敗したコマンドは、適切にエラーメッセージを返します

エージェントによる観測向けのツール設計

この MCP サーバーは、AI エージェントとうまく連携するパターンに従っています。

1. ブロッキング方式の観測操作：monitor_topic などのツールは指定された時間だけブロックするため、エージェントは自然な形で結果を待つことができます
2. 上限付きの時間枠：すべての監視ツールには最大実行時間（通常は 5～30 秒）が設定されており、無期限に待機することを防ぎます
3. 段階的なデータ収集：ツールはデータを段階的に収集し、観測時間枠の終了時に結果を返します
4. 明確な出力形式：結果は構造化されたテキストであるため、エージェントは簡単に解析して推論できます

Copilot での使用例

この MCP を使用する Copilot エージェントは、次のことができます。

Agent: "What topics are currently being published?"
[Uses: list_ros_topics]

Agent: "Let me observe the /cmd_vel topic for 5 seconds"
[Uses: monitor_topic with topic_name="/cmd_vel", duration_seconds=5]
[Waits 5 seconds for data collection]

Agent: "Here are the velocity commands being sent: [parsed data]"

Agent: "Show me how all nodes are connected"
[Uses: generate_ros_graph with output_format="text"]

Agent: "Let me try publishing a test message to the /cmd_vel topic"
[Uses: publish_to_topic]

Agent: "Let me check if any node is having issues"
[Uses: check_ros_system_status with include_diagnostics=true]

制限事項

• 一部の ROS 2 CLI コマンドでは、ROS 2 環境が適切にソースされている必要があります
• TF2 の監視には、tf2_tools パッケージがインストールされている必要があります
• サーバーは現在の環境でコマンドを実行するため、ROS 2 が適切にインストールされていることを確認してください
• 実行時間の長い操作はタイムアウトする場合があります。必要に応じて期間パラメーターを調整してください

今後の拡張

• ROS 2 bag の記録／再生との統合
• パラメーターサーバーの監視
• アクションクライアント／サーバーインターフェース
• rqt プラグインとのライブ統合
• Rviz2 データストリーミング
• カスタムメッセージ型の解析
• コマンドライン

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します。すべてのツールが適切にエラーを処理し、適切なパラメーター検証を含むようにしてください。