Reachy Mini Mcp

Reachy Mini MCP サーバー

FastMCPを使用して、Reachy Miniロボットを制御するModel Context Protocol（MCP）サーバーです。

メモ

完全なConversation Appをお探しですか？ このリポジトリには、Reachy Miniを自律型会話ロボットにする完全な「Conversation Stack」（聴覚 + LLM + 会話ロジック）も含まれています。

Dockerセットアップは、この会話アプリケーション全体を実行するためのものです。

👉 Conversation Stackの概要を読む

👉 Dockerセットアップの完全ガイド

このMCPサーバーには、Reachy Miniの頭部の動き、アンテナ、カメラを制御し、さまざまなジェスチャーや感情表現を実行するための包括的なツールが用意されています。

ロードマップ

MCP

• 音声：TTS、piper
• エージェント層
• アクションのキューに対応
• 割り込みに対応
• 胴体の動きに対応、reachy-mini python SDK

会話アプリ

• 聴覚：
  • VAD、WebRTCVAD / SileroVAD
  • STT、faster-whisper
• 視覚
• メモリ：
  • ファイル
  • ベクトルDB
  • ベクトルグラフDB
• 成長、夜間のファインチューニングに対応
• MQTTに対応
• autonomous-intelligenceリポジトリに移行

機能

動作と音声の制御

• 頭部の制御：3D空間（x、y、z）で頭部を動かし、向き（roll、pitch、yaw）を指定します
• アンテナの制御：左右のアンテナを個別に制御します
• 音声（TTS）：動作中にロボットに話させます（speechパラメーターを使用）
• ジェスチャー：定義済みのジェスチャー（挨拶、はい、いいえ、考え中、祝福）を実行します
• 感情：感情（うれしい、悲しい、好奇心、驚き、困惑）を表現します
• 方向を見る：ロボットに特定の方向（上、下、左、右）を見させます

モニタリングと制御

• 状態のモニタリング：ロボットの全体状態、頭部の状態、アンテナの状態、カメラの状態を取得します
• 電源管理：ロボットの電源をオン／オフにします
• 緊急停止：すべての動作をただちに停止します
• ヘルスステータス：ロボットの健全性とシステム状態をモニタリングします

高度な機能

• コマンドシーケンス：1回の呼び出しで複数のロボット操作を実行します（新機能！）
• 統合インターフェース：単一のoperate_robotツールからすべての機能にアクセスします
• リポジトリベースのツール：JSON定義を使用した、簡単に拡張できるツールシステムです

前提条件

1. Python 3.10+（Python 3.10～3.13でテスト済み）
2. Reachy Miniロボット：USB接続またはワイヤレス接続の実機ロボット、あるいはMuJoCoで実行中のシミュレーション
3. Reachy Mini Daemon：localhost:8000（デフォルト）で実行されている必要があります

インストール

このプロジェクトはpipでインストール可能なディストリビューションreachy-mini-mcpとして提供され、MCP サーバーと管理用のCLI（reachy-mini-mcp）の両方が含まれています。

# Manager CLI only (pure stdlib — show/install/uninstall/doctor/overview):
uv tool install reachy-mini-mcp        # or: pipx install reachy-mini-mcp

# To actually run the server, add the [server] extra (and [tts] for speech):
pip install "reachy-mini-mcp[server]"          # MCP stdio server
pip install "reachy-mini-mcp[server,tts]"      # + Piper TTS
pip install "reachy-mini-mcp[openai]"          # OpenAI-compatible HTTP server

ソースをチェックアウトした状態からは、./setup.shを実行すると.venvが作成され、[server,tts]を含めてパッケージが編集可能モードでインストールされます。

管理用CLI

reachy-mini-mcpはMCPサーバー管理ツールです。エージェントやオペレーターにサーバーの登録方法と実行方法を案内し、代わりに実行することもできます。

reachy-mini-mcp overview     # one-screen status (also the no-arg default)
reachy-mini-mcp show         # print the mcp.json snippet for this machine
reachy-mini-mcp explain      # how MCP registration works + where configs live
reachy-mini-mcp install --client claude-code --scope project   # set it up
reachy-mini-mcp uninstall --client claude-code --scope project # put it down
reachy-mini-mcp doctor       # diagnose deps, daemon, and client registration
reachy-mini-mcp serve        # run the FastMCP stdio server (what mcp.json calls)

install／uninstallの対象は、claude-code（プロジェクトの.mcp.jsonまたはユーザーの~/.claude.json）、claude-desktop、cursor、または任意の--path FILEです。既存の設定に統合され（ほかのサーバー設定は保持されます）、書き込まずに結果を表示する--dry-runも指定できます。

MCPクライアントへの登録

追加するmcp.jsonのエントリーです（reachy-mini-mcp showでも出力されます）。

{
  "mcpServers": {
    "reachy-mini": {
      "command": "reachy-mini-mcp",
      "args": ["serve"],
      "env": { "REACHY_BASE_URL": "http://localhost:8000" }
    }
  }
}

MCPサーバーの実行

ステップ 1：Reachy Mini デーモンを起動する

MCP サーバーを起動する前に、Reachy Mini デーモンを実行しておく必要があります。

👉 Reachy Mini デーモンの公式セットアップガイドに従ってください

デーモンが実行中で、アクセス可能であることを確認してください（デフォルト：http://localhost:8000）。

ステップ 2：MCP サーバーを起動する

reachy-mini-mcp serve

同等の実行方法：python -m reachy_mini_mcp serve、またはソースチェックアウトの場合は fastmcp run reachy_mini_mcp/server.py。

これで MCP サーバーが実行され、MCP クライアントからの接続を受け付ける準備ができました。

利用可能な MCP ツール

統合ツール：operate_robot

この MCP サーバーは、すべてのロボット制御機能にアクセスできる 1 つの MCP ツールを公開します。

ツール	説明
operate_robot(tool_name, parameters)	名前を指定して任意のロボット制御操作を動的に実行するメタツールです。
operate_robot(commands)	複数の操作を順番に実行するシーケンスモードです。

この統合インターフェースを使うと、ロボット制御操作を個別に、またはシーケンスとして呼び出せます。

単一コマンドモード：

# Example: Get robot state
operate_robot("get_robot_state")

# Example: Express emotion with parameters
operate_robot("express_emotion", {"emotion": "happy"})

# Example: Move head with multiple parameters
operate_robot("move_head", {"z": 10, "duration": 2.0, "mm": True})

シーケンスモード（新機能！）：

# Example: Execute multiple commands in sequence
operate_robot(commands=[
    {"tool_name": "perform_gesture", "parameters": {"gesture": "greeting"}},
    {"tool_name": "nod_head", "parameters": {"duration": 2.0, "angle": 15}},
    {"tool_name": "move_antennas", "parameters": {"left": 30, "right": -30, "duration": 1.5}},
    {"tool_name": "look_at_direction", "parameters": {"direction": "left", "duration": 1.0}}
])

注： ツール名は正確に一致させる必要があります。正しいツール名は get_robot_status ではなく、get_robot_state です。

利用可能なロボット操作

すべての操作は operate_robot ツールから利用できます。利用可能な操作は以下のとおりです。

基本状態と制御

操作	説明
get_robot_state	すべてのコンポーネントを含む、ロボットの全状態を取得します
get_head_state	現在の頭部の位置と向きを取得します
get_antennas_state	現在のアンテナの位置を取得します
get_camera_state	カメラの状態を取得します
get_power_state	ロボットの電源がオンかオフかを確認します
get_health_status	全体的なヘルス状態を取得します
turn_on_robot	ロボットの電源を入れます
turn_off_robot	ロボットの電源を切ります
stop_all_movements	すべての動きを緊急停止します

頭部の動き

操作	説明
move_head	頭部を指定したポーズに動かします（パラメーター：x、y、z、roll、pitch、yaw、duration）
reset_head	頭部をニュートラル位置に戻します
nod_head	ロボットにうなずかせます（パラメーター：duration、angle）
shake_head	ロボットに頭を振らせます（パラメーター：duration、angle）
tilt_head	頭部を左右に傾けます（パラメーター：direction、angle、duration）
look_at_direction	指定した方向を見ます（パラメーター：direction - up/down/left/right、duration）

アンテナの動き

操作	説明
move_antennas	アンテナを指定した位置に動かします（パラメーター：left、right、duration）
reset_antennas	アンテナをニュートラル位置に戻します

感情とジェスチャー

操作	説明
express_emotion	感情を表現します（パラメーター：emotion - happy/sad/curious/surprised/confused）
perform_gesture	ジェスチャーを行います（パラメーター：gesture - greeting/yes/no/thinking/celebration）

カメラ

操作	説明
get_camera_image	カメラから画像を撮影します
get_camera_state	カメラの状態を取得します

使用例

すべての操作は operate_robot ツールから呼び出します。以下に例を示します。

例 1：基本的な頭部の動き

# In your MCP client (e.g., Claude Desktop)
# Move head up 10mm and tilt 15 degrees
operate_robot("move_head", {"z": 10, "roll": 15, "duration": 2.0})

# Return to neutral
operate_robot("reset_head")

例 2：感情を表現する

# Make the robot look happy
operate_robot("express_emotion", {"emotion": "happy"})

# Make the robot look curious
operate_robot("express_emotion", {"emotion": "curious"})

# Return to neutral
operate_robot("express_emotion", {"emotion": "neutral"})

例 3：ジェスチャーを行う

# Wave hello
operate_robot("perform_gesture", {"gesture": "greeting"})

# Nod yes
operate_robot("perform_gesture", {"gesture": "yes"})

# Shake no
operate_robot("perform_gesture", {"gesture": "no"})

例 4：複雑なインタラクション

# Turn on the robot
operate_robot("turn_on_robot")

# Check state
state = operate_robot("get_robot_state")

# Make robot look around
operate_robot("look_at_direction", {"direction": "left", "duration": 1.5})
operate_robot("look_at_direction", {"direction": "right", "duration": 1.5})
operate_robot("look_at_direction", {"direction": "forward"})

# Express surprise
operate_robot("express_emotion", {"emotion": "surprised"})

# Perform celebration
operate_robot("perform_gesture", {"gesture": "celebration"})

# Turn off when done
operate_robot("turn_off_robot")

例 5：アンテナを制御する

# Move antennas independently
operate_robot("move_antennas", {"left": 30, "right": -30, "duration": 1.0})

# Reset to neutral
operate_robot("reset_antennas")

例 6：コマンドシーケンス（新機能！）

コマンドシーケンスを使って、複雑なロボットの動作を実行します。

# Greeting sequence
operate_robot(commands=[
    {"tool_name": "express_emotion", "parameters": {"emotion": "happy"}},
    {"tool_name": "perform_gesture", "parameters": {"gesture": "greeting"}},
    {"tool_name": "nod_head", "parameters": {"duration": 1.5, "angle": 10}},
    {"tool_name": "reset_head", "parameters": {}}
])

# Curious behavior - look around
operate_robot(commands=[
    {"tool_name": "express_emotion", "parameters": {"emotion": "curious"}},
    {"tool_name": "move_antennas", "parameters": {"left": 30, "right": 30, "duration": 1.0}},
    {"tool_name": "look_at_direction", "parameters": {"direction": "left", "duration": 1.0}},
    {"tool_name": "look_at_direction", "parameters": {"direction": "right", "duration": 1.0}},
    {"tool_name": "look_at_direction", "parameters": {"direction": "forward", "duration": 0.5}}
])

# Initialization routine
operate_robot(commands=[
    {"tool_name": "turn_on_robot", "parameters": {}},
    {"tool_name": "reset_head", "parameters": {}},
    {"tool_name": "reset_antennas", "parameters": {}},
    {"tool_name": "get_robot_state", "parameters": {}}
])

コマンドシーケンスの詳細については、SEQUENCE_COMMANDS.md を参照してください。

MCP 対応クライアントでの使用

最も簡単な方法は、マネージャー CLI に設定を書き込ませることです。

reachy-mini-mcp install --client claude-desktop   # or claude-code / cursor

手動で設定する場合は、クライアントの設定ファイルに以下を追加してください（同じ JSON を Claude Desktop、Claude Code、Cursor で使用できます。設定ファイルの場所は以下を参照してください）。

{
  "mcpServers": {
    "reachy-mini": {
      "command": "reachy-mini-mcp",
      "args": ["serve"],
      "env": { "REACHY_BASE_URL": "http://localhost:8000" }
    }
  }
}

設定ファイルの場所：

• Claude Desktop — macOS：~/Library/Application Support/Claude/claude_desktop_config.json； Linux：~/.config/Claude/claude_desktop_config.json； Windows：%APPDATA%\Claude\claude_desktop_config.json
• Claude Code — プロジェクト：./.mcp.json；ユーザー：~/.claude.json
• Cursor — プロジェクト：./.cursor/mcp.json；ユーザー：~/.cursor/mcp.json

設定を編集したら、クライアントを再起動してください。Reachy Mini のツールを会話で使用できるようになります。

MCP プロンプト

サーバーには、次の便利なプロンプトが含まれています。

• control_prompt - Reachy Mini を制御するためのガイドライン
• safety_prompt - 安全に関するガイドラインと制限事項

アーキテクチャ

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│  MCP Client     │◄───────►│  FastMCP Server  │◄───────►│ Reachy Daemon   │
│  (Claude, etc)  │  stdio  │ (reachy-mini-mcp │  HTTP   │  (localhost:8000)│
│                 │         │      serve)      │         │                 │
└─────────────────┘         └──────────────────┘         └─────────────────┘
                                                                    │
                                                                    ▼
                                                          ┌─────────────────┐
                                                          │  Reachy Mini    │
                                                          │  Robot/Sim      │
                                                          └─────────────────┘

開発

リポジトリベースのツールシステム

この MCP サーバーでは、ツールの定義にリポジトリベースのアプローチを採用しているため、高い拡張性とカスタマイズ性を備えています。ツールは Python にハードコードするのではなく、JSON ファイルで定義します。

主なメリット：

• ✅ サーバーコードを変更せずに新しいツールを追加できます
• ✅ JSON ファイルを編集してツールの動作をカスタマイズできます
• ✅ ツール定義のバージョン管理や共有が簡単です
• ✅ 複雑な操作をスクリプトで実行できます

リポジトリ構成：

tools_repository/
├── tools_index.json          # Root file listing all tools
├── *.json                    # Individual tool definitions
└── scripts/                  # Python scripts for complex tools
    ├── nod_head.py
    ├── shake_head.py
    ├── express_emotion.py
    └── perform_gesture.py

新しいツールの追加

tools_repository/scripts/my_tool.py に Python スクリプトを作成します。

async def execute(make_request, create_head_pose, params):
    """Execute the tool."""
    # Your logic here
    await make_request("POST", "/api/endpoint1", json_data={...})
    await asyncio.sleep(1.0)
    await make_request("POST", "/api/endpoint2", json_data={...})
    return {"status": "success"}

次に、JSON ファイル（例：tools_repository/my_tool.json）を作成します。

{
  "name": "my_tool",
  "description": "Description of what my tool does",
  "parameters": {
    "required": [
      {"name": "param1", "type": "string", "description": "First parameter"}
    ],
    "optional": [
      {"name": "param2", "type": "number", "default": 1.0, "description": "Second parameter"}
    ]
  },
  "execution": {
    "type": "script",
    "script_file": "my_tool.py"
  }
}

tools_repository/tools_index.json に追加します。

{
  "name": "my_tool",
  "enabled": true,
  "definition_file": "my_tool.json"
}

サーバーを再起動すると、ツールを使用できるようになります。

ツールのテスト

ツール定義を検証します。

python test_repository.py

これにより、すべての JSON ファイルが有効であり、スクリプトファイルが存在することを確認できます。

リソース

• Reachy Mini GitHub
• FastMCP ドキュメント
• Model Context Protocol 仕様

ライセンス

このプロジェクトは MIT License の下でライセンスされています。これには、このリポジトリ内の会話アプリと聴覚アプリも含まれますが、Reachy Mini Daemon には適用されません。

貢献

貢献を歓迎します。お気軽にイシューやプルリクエストを送信してください。

サポート

次の問題については、それぞれ以下をご利用ください。

• この MCP サーバー：このリポジトリでイシューを作成してください
• Reachy Mini ロボット：Reachy Mini GitHub Issuesをご覧ください

クレジット

• Marvin による FastMCP を使用して構築
• Pollen Robotics & Hugging Face による Reachy Mini 向け
• Model Context Protocol 仕様に準拠