Reachy Mini MCP

🚀 Reachy Mini MCP 服務器

Reachy Mini MCP 服務器是一個用於控制 Reachy Mini 機器人的 MCP（模型上下文協議）服務器。它允許 Claude Desktop 和其他 MCP 客戶端通過自然語言與 Reachy Mini 機器人進行交互。

✨ 主要特性

• 舞蹈功能：播放編排好的舞蹈動作。
• 情感表達：展現預先錄製的情感。
• 頭部移動：使機器人頭部向不同方向轉動。
• 相機功能：從機器人的相機捕獲圖像。
• 頭部追蹤：開啟面部追蹤模式。
• 🎤 即時本地文本轉語音：文本轉語音功能完全在設備上運行，採用流式音頻，無需雲 API，無延遲，無 API 費用。
• 運動控制：停止運動並查詢機器人狀態。

📦 安裝指南

# 克隆倉庫
cd reachy-mini-mcp

# 創建虛擬環境
uv venv --python 3.10
source .venv/bin/activate

# 安裝依賴
uv pip install -e .

# 可選：安裝相機支持
uv pip install -e ".[camera]"

# 可選：安裝語音支持（文本轉語音）
uv pip install -e ".[speech]"

📚 詳細文檔

配置

將 .env.example 複製為 .env 並進行配置：

cp .env.example .env

可用的環境變量如下：

使用方法

直接運行服務器

reachy-mini-mcp

使用 Claude Code CLI

使用 claude mcp add 命令添加 MCP 服務器：

# 從源代碼構建（克隆倉庫後）
claude mcp add --transport stdio reachy-mini -- bash -c "cd /path/to/reachy-mini-mcp && uv run reachy-mini-mcp"

# 啟用相機支持
claude mcp add --transport stdio reachy-mini --env REACHY_MINI_ENABLE_CAMERA=true -- bash -c "cd /path/to/reachy-mini-mcp && uv run reachy-mini-mcp"

# 使用自定義機器人名稱
claude mcp add --transport stdio reachy-mini --env REACHY_MINI_ROBOT_NAME=my-robot -- bash -c "cd /path/to/reachy-mini-mcp && uv run reachy-mini-mcp"

集成到 Claude Desktop

將以下內容添加到你的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "reachy-mini": {
      "command": "reachy-mini-mcp",
      "env": {
        "REACHY_MINI_ENABLE_CAMERA": "true"
      }
    }
  }
}

如果使用虛擬環境：

{
  "mcpServers": {
    "reachy-mini": {
      "command": "/path/to/reachy-mini-mcp/.venv/bin/reachy-mini-mcp",
      "env": {
        "REACHY_MINI_ENABLE_CAMERA": "true"
      }
    }
  }
}

可用工具

dance

讓機器人播放舞蹈動作。 參數：

• move（字符串，可選）：舞蹈名稱或 "random"。默認值："random"
• repeat（整數，可選）：重複次數。默認值：1 可用舞蹈動作：simple_nod, head_tilt_roll, side_to_side_sway, dizzy_spin, stumble_and_recover, interwoven_spirals, sharp_side_tilt, side_peekaboo, yeah_nod, uh_huh_tilt, neck_recoil, chin_lead, groovy_sway_and_roll, chicken_peck, side_glance_flick, polyrhythm_combo, grid_snap, pendulum_swing, jackson_square

play_emotion

播放預先錄製的情感。 參數：

• emotion（字符串，必需）：要播放的情感名稱

move_head

讓機器人的頭部向某個方向移動。 參數：

• direction（字符串，必需）：可選值為 "left"、"right"、"up"、"down"、"front"
• duration（浮點數，可選）：移動持續時間（秒）。默認值：1.0

camera

從機器人的相機捕獲圖像。 返回值：Base64 編碼的 JPEG 圖像 注意：需要 REACHY_MINI_ENABLE_CAMERA=true

head_tracking

切換頭部追蹤模式。 參數：

• enabled（布爾值，必需）：true 表示啟用，false 表示禁用

stop_motion

立即停止所有當前和排隊的運動。

speak

讓機器人使用即時本地文本轉語音功能說話，並伴有自然的頭部移動動畫。 參數：

• text（字符串，必需）：要說出的文本
• voice（字符串，可選）：要使用的語音。默認值："alba" 可用語音：alba, marius, javert, jean, fantine, cosette, eponine, azelma 注意：需要 pocket-tts 包。使用 uv pip install -e ".[speech]" 進行安裝 主要亮點：
• 完全本地運行：完全在你的機器上運行，安裝後無需互聯網連接。
• 即時流式傳輸：音頻即時生成和流式傳輸，實現即時響應。
• 零 API 費用：無需雲 TTS 服務，無按字符收費，可無限使用。
• 低延遲：直接本地處理意味著文本輸入和語音輸出之間的延遲最小。
• 隱私保護：你的文本不會離開你的設備。

機器人在說話時頭部會自然擺動，營造更逼真的交互體驗。

get_status

獲取當前機器人的狀態，包括連接狀態、隊列大小和當前姿勢。

要求

• Python 3.10 及以上版本
• Reachy Mini SDK (reachy_mini>=1.2.7)
• 運行 reachy-mini-daemon 或進行模擬
• 與機器人的 Zenoh 網絡連接

開發

# 安裝開發依賴
uv pip install -e ".[dev]"

# 運行代碼檢查工具
ruff check .

# 運行類型檢查工具
mypy src/

📄 許可證

本項目採用 MIT 許可證。