AI导哈

机器人控制接口

通过MCP协议控制Reachy Mini机器人或模拟器的接口服务，支持AI助手调用视觉、运动、音频等16种工具。

  • by ArturSkowronski
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 ArturSkowronski/reachy-mini-mcp

使用说明

Reachy迷你MCP

控制 Reachy Mini Claude、ChatGPT或任何MCP兼容客户端的机器人（或模拟器）。

Quickstart 
uv sync --extra reachy
uv run reachy.py
Simulator demo 
uv sync --extra reachy-sim
uv run python reachy_debug.py

试运行（视频）

短暂的“模拟运行” reachy_debug.py 顺序演示运行器（模拟器）：步骤通知、动作、视觉和伪影。

在GitHub Pages上观看模拟运行视频

运作原理

AI Assistant  --stdio-->  MCP Server (reachy.py)  -->  ReachyMini SDK  -->  Robot / Simulator

服务器通过以下方式公开16个工具、4个提示和4个资源 模型上下文协议人工智能助手调用这些工具来穿透机器人的摄像头、移动机器人、表达情感、播放声音或检测音频方向——人工智能方面不需要机器人知识。

安装

先决条件

安装服务器

git clone https://github.com/ArturSkowronski/reachy-mini-mcp.git
cd reachy-mini-mcp
uv sync

或者使用pip：

pip install -e .

配置您的MCP客户端

将服务器添加到MCP客户端配置中。具体位置取决于客户：

克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "reachy-mini": {
      "command": "uv",
      "args": ["--directory", "/path/to/reachy-mini-mcp", "run", "reachy.py"]
    }
  }
}

克劳德代码 (.mcp.json 在项目根目录中）：

{
  "mcpServers": {
    "reachy-mini": {
      "command": "uv",
      "args": ["--directory", "/path/to/reachy-mini-mcp", "run", "reachy.py"]
    }
  }
}

通用标准传输：

uv run reachy.py

ElevenLabs TTS（可选）

要启用 speak_text 工具，设置这些环境变量：

export ELEVENLABS_API_KEY="your-api-key"
export ELEVENLABS_VOICE_ID="your-voice-id"
#
# Optional override prefix (takes precedence):
# export REACHY_ELEVENLABS_API_KEY="your-api-key"
# export REACHY_ELEVENLABS_VOICE_ID="your-voice-id"

默认语音（预制/免费层友好）： George 带语音ID JBFqnCBsd6RMkjVDRZzb.

最喜欢的声音（作者偏好）： Horatius 带语音ID qXpMhyvQqiRxWQs4qSSB.

可选覆盖： ELEVENLABS_MODEL_ID （默认值： eleven_multilingual_v2), ELEVENLABS_OUTPUT_FORMAT （默认值： mp3_44100_128).

WAV支持：如果您的ElevenLabs计划允许，您可以设置 ELEVENLABS_OUTPUT_FORMAT=wav_44100 以获得WAV输出而不是MP3。

MP3与WAV播放说明

  • 默认TTS输出为MP3(mp3_44100_128)因为它适用于ElevenLabs的较低层。
  • 一些Reachy音频后端/环境可能没有可用的MP3解码。在这种情况下，即使WAV工作，MP3播放也可能失败。
  • 如果您需要ElevenLabs直接退回WAV(wav_44100)ElevenLabs要求更高的级别（最低 专业版).
  • 要强制WAV输出（如果可用），请通过环境变量覆盖输出格式：
    • REACHY_ELEVENLABS_OUTPUT_FORMAT=wav_44100 （首选，优先）
    • 或 ELEVENLABS_OUTPUT_FORMAT=wav_44100

环境变量

概述：

  • NO_COLOR：禁用ANSI颜色 reachy_debug.py 输出。

调试运行器(reachy_debug.py):

  • REACHY_DEBUG_ANNOUNCE_PAUSE_S （默认值： 0.6)：在运行步骤之前，在每次公告后暂停。
  • REACHY_DEBUG_TTS_SPEED （默认值： 0.8)ElevenLabs的语音速度。

ElevenLabs（使用 speak_text 和 reachy_debug.py 公告）：

  • REACHY_ELEVENLABS_API_KEY 或 ELEVENLABS_API_KEY （TTS必需）：API键。 REACHY_ 前缀值优先。
  • REACHY_ELEVENLABS_VOICE_ID 或 ELEVENLABS_VOICE_ID （可选）：语音id。默认为 JBFqnCBsd6RMkjVDRZzb （乔治）如果没有设定。
  • REACHY_ELEVENLABS_MODEL_ID 或 ELEVENLABS_MODEL_ID （可选）：模型id（默认值： eleven_multilingual_v2).
  • REACHY_ELEVENLABS_OUTPUT_FORMAT 或 ELEVENLABS_OUTPUT_FORMAT （可选）：输出格式（默认值： mp3_44100_128，可选 wav_44100 如果你的计划允许的话）。

可用工具

工具 说明
capture_image 从机器人的高清摄像头捕获JPEG帧
scan_surroundings 将相机从多个角度平移，并返回一组全景图像
track_face 通过OpenCV检测一张脸，然后转头面对它
move_head 6-DOF头部定位（x/y/z，单位为毫米，横滚/俯仰/偏航，单位为度）
move_antennas 独立天线控制（-3.14至3.14弧度）
look_at_point 将头部朝向世界坐标系中的三维点
express_emotion 表情驱动的情绪系统，具有同步的动作和声音
play_sound 播放内置声音（唤醒、睡眠、困惑1、不耐烦1、跳舞1、计数）
speak_text 通过ElevenLabs API进行文本到语音传输，通过机器人扬声器播放
detect_sound_direction 麦克风阵列到达方向+语音检测
wake_up 内置有声音的问候动画
go_to_sleep 内置有声音的告别动画
nod 上下点头表示“是”或同意
shake_head 左右摇头表示“不”或不同意
reset_position 将头部和天线恢复到中性休息姿势
do_barrel_roll 精心编排的头部倾斜+天线摆动序列

资源

服务器还公开了MCP资源，让AI助手动态发现机器人的能力：

资源URI 描述
reachy://emotions 支持的表情到表情的映射
reachy://sounds 可用的内置声音名称
reachy://limits 物理限制（天线范围、头部自由度、相机规格）
reachy://capabilities 按类别（视觉、运动、表情、音频、生命周期）分组的所有工具

视觉

capture_image 从Reachy Mini的广角高清相机中抓取一帧，并通过MCP协议将其作为内联JPEG内容返回。AI助手在对话中直接接收图像——没有文件路径，没有URL，也没有额外的设置。

scan_surroundings 通过在多个角度上平移相机并在单个响应中返回所有帧，进一步实现了这一点：

User:  "Look around and describe the room"

       Claude calls scan_surroundings(steps=5, yaw_range=120)
       <- Robot pans from -60deg to +60deg in 5 steps
       <- MCP returns 5 labeled JPEG frames + summary text

Claude: "Starting from the left I can see a window with blinds,
         then a whiteboard, your desk with two monitors in the
         center, a bookshelf to the right, and a door at the
         far right."

相机从OpenCV返回一个标准的BGR numpy帧，该帧经过JPEG压缩并作为MCP交付 ImageContent任何支持图像输入的多模态AI模型都可以处理它——Claude、GPT-4o、Gemini等。

工具注释

每个工具都带有语义注释，告诉AI客户端如何安全地使用它：

注释 含义 工具
readOnlyHint 不会改变机器人状态 capture_image, detect_sound_direction
idempotentHint=true 可以安全地反复呼叫 capture_image, detect_sound_direction
idempotentHint=false 重复通话重复动作/成本 所有动作/手势/音频工具，包括 speak_text
destructiveHint=false 没有不可逆的操作 所有工具
openWorldHint 呼叫外部服务 speak_text （ElevenLabs API）

提示

预构建的提示模板，指导AI助手完成常见的机器人交互场景：

提示 描述
greet_user 唤醒机器人，表达快乐，并用名字问候
explore_room 用相机扫描周围环境并描述环境
react_to_conversation 在聊天过程中使用手势和情绪做出身体反应
find_person 使用摄像头和面部跟踪来定位和跟踪一个人

情感系统

express_emotion 将表情符号角色映射到精心编排的动作：

表情符号 情绪 行为
😊 快乐 天线竖起，姿势欢快，舞蹈声
😕 头部倾斜、天线不对称、声音混乱
😤 不耐烦 天线快速移动，不耐烦的声音
😴 困倦 有声音的睡眠姿势
👋 问候 唤醒动画
🤔 思考 沉思的头倾斜，天线散开
😮 惊讶 天线高，头向后
😢 悲伤 天线和低头
🎉 庆祝 充满活力的摆动，舞蹈声
😐 中立 回到静止位置

发展

# Install with dev dependencies
uv sync --extra dev

# Run all tests
uv run pytest -v

# Unit tests only
uv run pytest -v -m "not integration"

# Integration tests only (MCP protocol layer)
uv run pytest -v -m integration

# Lint
uv run ruff check . && uv run ruff format --check .

# Set up pre-commit hooks
pre-commit install

直接机器人测试

对于一键式完整顺序调试演示（移动、手势、音频、视觉、跟踪），并进行每一步状态检查：

uv sync --extra reachy
# If you want to auto-spawn the simulator daemon, also install:
uv sync --extra reachy-sim
uv run python reachy_debug.py

reachy_debug.py 现在：

  • 宣布每个即将进行的测试步骤（如果配置了，则通过ElevenLabs进行语音，否则通过控制台回退）。
  • 按顺序执行完整的演示套件。
  • 将所有捕获的图像和降价运行摘要保存到 results/run-YYYYMMDD-HHMMSS/.
  • 为运行生成单个报告文件： run_report.md.

GitHub页面

此仓库包含一个静态GitHub Pages网站，位于 docs/ （嵌入了模拟运行视频）。

发布：GitHub仓库设置->页面->“构建和部署”->来源：“从分支部署”->分支： main ->文件夹： /docs.

相关 MCP