Reachy Mini Mcp

Reachy Mini MCP 服务

一个使用 FastMCP 控制 Reachy Mini 机器人的模型上下文协议（MCP）服务。

说明

想了解完整的对话应用？ 此代码库还包含完整的“对话栈”（听觉 + 大模型 + 对话逻辑），可将 Reachy Mini 打造成自主对话机器人。

Docker 配置专为运行此完整对话应用而设。

👉 阅读对话栈概览

👉 Docker 完整配置指南

此 MCP 服务提供全面的工具集，可用于控制 Reachy Mini 的头部动作、天线和摄像头，以及执行各种手势和情绪表达。

路线图

MCP

• 语音：TTS、piper
• Agent 层
• 支持动作队列
• 支持中断
• 支持移动身体，reachy-mini python SDK

对话应用

• 听觉：
  • VAD、WebRTCVAD / SileroVAD
  • STT、faster-whisper
• 视觉
• 记忆：
  • 文件
  • 向量数据库
  • 向量图数据库
• 成长，支持每晚微调
• 支持 MQTT
• 移至 autonomous-intelligence 代码库

功能

动作与语音控制

• 头部控制：在 3D 空间中移动头部（x、y、z），并调整朝向（roll、pitch、yaw）
• 天线控制：分别控制左、右天线
• 语音（TTS）：让机器人在执行动作时说话（通过 speech 参数）
• 手势：执行预定义手势（问候、是、否、思考、庆祝）
• 情绪：表达情绪（开心、悲伤、好奇、惊讶、困惑）
• 方向注视：让机器人朝特定方向看（上、下、左、右）

监控与控制

• 状态监控：获取机器人完整状态、头部状态、天线状态和摄像头状态
• 电源管理：开启/关闭机器人
• 紧急停止：立即停止所有动作
• 健康状态：监控机器人健康状况和系统状态

高级功能

• 命令序列：在一次调用中执行多个机器人操作（新增！）
• 统一接口：通过一个 operate_robot 工具使用所有功能
• 基于代码库的工具：使用 JSON 定义的易扩展工具系统

前提条件

1. Python 3.10+（已使用 Python 3.10-3.13 测试）
2. Reachy Mini 机器人：通过 USB 或无线连接的实体机器人，或在 MuJoCo 中运行的模拟环境
3. Reachy Mini 守护进程：必须在 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 服务管理器——它会告知 Agent 或操作者如何注册和运行此服务，也可以代为完成：

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 服务提供一个 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_state，而不是 get_robot_status。

可用的机器人操作

所有操作都可通过 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 服务采用基于仓库的方式定义工具，具有很强的可扩展性和可定制性。工具定义在 JSON 文件中，而不是硬编码在 Python 中。

主要优点：

• ✅ 无需修改服务代码即可添加新工具
• ✅ 通过编辑 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 许可证，其中包括此仓库内的对话和听力应用；许可证不适用于 Reachy Mini Daemon。

贡献

欢迎贡献！欢迎提交问题或拉取请求。

支持

关于以下内容的问题：

• 此 MCP 服务：在此仓库中提出问题
• Reachy Mini 机器人：访问 Reachy Mini GitHub Issues

致谢

• 使用 Marvin 开发的 FastMCP 构建
• 适用于 Pollen Robotics 和 Hugging Face 开发的 Reachy Mini
• 遵循 Model Context Protocol 规范