JinDaGe - reachy-mini-mcp MCP Details

article

README

🚀 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_ROBOT_NAME | 用于 Zenoh 发现的机器人名称 | reachy-mini | | REACHY_MINI_ENABLE_CAMERA | 启用相机捕获功能 | false | | REACHY_MINI_HEAD_TRACKING_ENABLED | 启动时启用头部追踪功能 | false |

使用方法

直接运行服务器

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 许可证。

reachy-mini-mcp