ros2-mcp-server

ros2-mcp-server

ros2-mcp-server は、Model Context Protocol（MCP）と ROS 2 を連携させ、AI アシスタントが ROS 2 トピック経由でロボットを制御できるようにする、Python ベースのサーバーです。FastMCP を通じてコマンドを処理し、ROS 2 ノードとして動作して、geometry_msgs/Twist メッセージを /cmd_vel トピックにパブリッシュし、ロボットの動きを制御します。

この実装では、「5 秒間、0.2 m/s で前進して停止する」といったコマンドに対応しており、/cmd_vel パブリッシャーの名前は pub_cmd_vel です。

特長

• MCP 連携：FastMCP を使用して、MCP クライアント（例：Claude）からのコマンドを処理します。
• ROS 2 ネイティブ：ROS 2 ノードとして動作し、/cmd_vel に直接パブリッシュします。
• 時間ベースの制御：指定時間だけ移動して停止するなど、継続時間を指定した移動コマンドに対応しています。
• 非同期処理：FastMCP の asyncio と ROS 2 のイベントループを組み合わせて、効率的に動作します。

前提条件

• ROS 2：Humble ディストリビューションがインストールされ、環境設定されていること。
• Python：バージョン 3.10（ROS 2 Humble との互換性に必要です）。
• uv：依存関係を管理する Python パッケージマネージャー。
• 依存関係：
  • rclpy：ROS 2 の Python クライアントライブラリ（ROS 2 とともにインストールされます）。
  • fastmcp：MCP サーバーの実装に使用する FastMCP フレームワーク。
  • numpy：ROS 2 のメッセージ型で必要です。

インストール

1. リポジトリのクローン：

   git clone https://github.com/kakimochi/ros2-mcp-server.git
   cd ros2-mcp-server
   

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 サーバーとして設定する必要があります。設定方法は次のとおりです。

Claude Desktop の場合

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. コマンドの例： ロボットに 0.2 m/s で 5 秒間前進するよう Claude に指示します。

   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
     

   • Claude を使用して移動コマンドを送信します。
   • Gazebo でロボットが動くことを確認します。

2. 実機のロボットを使用する場合：

   • ロボットが /cmd_vel トピックを正しくサブスクライブするように設定されていることを確認します。
   • Claude を使用して移動コマンドを送信します。
   • ロボットがコマンドに従って動くはずです。

3. 期待される出力：

   • サーバーは移動コマンドと停止コマンドをログに記録します。
   • Claude は "Successfully moved for 5.0 seconds and stopped" のような応答を受け取ります。

トラブルシューティング

• ROS 2 のログエラー：ログディレクトリのエラーが発生した場合は、ROS_LOG_DIR 環境変数が書き込み可能なディレクトリ（例：/tmp）に設定されていることを確認します。
• Python のバージョン不一致：ROS 2 Humble は Python 3.10 向けにビルドされているため、Python 3.10 を使用していることを確認します。
• 接続エラー：Claude で「Connection closed」エラーが報告される場合は、MCP サーバーの設定が正しく、すべての依存関係がインストールされていることを確認します。

ディレクトリ構成

ros2-mcp-server/
├── ros2-mcp-server.py  # Main server script integrating FastMCP and ROS 2
├── pyproject.toml      # Project dependencies and metadata
├── .python-version     # Python version specification
├── .gitignore          # Git ignore file
└── README.md           # This file

制限事項

• 単一のトピック：現在は Twist メッセージを使用する /cmd_vel をサポートしています。他のトピックやサービスに対応するには、ros2-mcp-server.py を拡張してください。
• 基本的なコマンド：現在は単純な移動コマンドをサポートしています。より複雑な動作には、追加の実装が必要です。

ライセンス

MIT License

Copyright (c) 2025 kakimochi

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

このプロジェクトでは FastMCP を使用しています。FastMCP は Apache License 2.0 の下でライセンスされています。FastMCP コンポーネントの使用にも、そのライセンスの条項が適用されます。

謝辞

• FastMCP と ROS 2 を使用して構築されています。