使用说明

Reachy迷你MCP服务器

一种模型上下文协议（MCP）服务器，用于控制 Reachy Mini 机器人使用 FastMCP.

[！注意] 正在寻找完整的对话应用程序？ 该存储库还包含完整的“对话栈”（听力+LLM+对话逻辑），它将Reachy Mini变成了一个自主的对话机器人。

这 Docker设置 专门用于运行此完整对话应用程序。

👉 阅读会话堆栈概述

👉 完整的Docker安装指南

此MCP服务器提供了一套全面的工具来控制Reachy Mini的头部运动、天线、相机，并执行各种手势和情绪表达。

路线图

主控程序

[]演讲：TTS，风笛手
[]代理层
[]队列操作支持
[]中断支持
[]移动体支持，获取mini-python SDK

对话应用程序

[]听证会：
- [ ] VAD，WebRTCVAD / SileroVAD
- []STT，更快的耳语
[]愿景
[]内存：
- []文件
- []矢量数据库
- []矢量图数据库
[]增长，夜间微调支持
[]MQTT支持
[]移动到自主智能仓库

特性

运动和语音控制

头部控制：在三维空间（x、y、z）中移动头部，并确定方向（滚动、俯仰、偏航）
天线控制：独立控制左右天线
演讲（TTS）：让机器人在执行动作时说话（通过 speech 参数）
手势：执行预定义的手势（问候、是、否、思考、庆祝）
情感：表达情绪（高兴、悲伤、好奇、惊讶、困惑）
方向观察：使机器人朝特定方向（上、下、左、右）看

监控与控制

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

高级功能

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

先决条件

Python 3.10+ （用Python 3.10-3.13测试）
Reachy迷你机器人：通过USB或无线连接的物理机器人，或在MuJoCo中运行的模拟
Reachy迷你守护进程：必须正在运行 localhost:8000 （默认）

安装

该项目以pip可安装分发的形式发货， reachy-mini-mcp，其中提供MCP 服务器 还有一个经理 命令行界面 (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 创建a .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服务器

第一步：启动Reachy迷你守护进程

在启动MCP服务器之前，您需要运行Reachy Mini守护进程。

👉 遵循官方Reachy迷你守护进程设置指南

确保守护进程正在运行且可访问（默认值： 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、滚动、俯仰、偏航、持续时间）
`reset_head`	将头部恢复到中立位置
`nod_head`	使机器人点头（参数：持续时间、角度）
`shake_head`	使机器人摇头（参数：持续时间、角度）
`tilt_head`	向左或向右倾斜头部（参数：方向、角度、持续时间）
`look_at_direction`	看一个方向（参数：方向-上/下/左/右，持续时间）

天线移动

操作	说明
`move_antennas`	将天线移动到特定位置（参数：左、右、持续时间）
`reset_antennas`	将天线返回到空档位置

情绪和手势

操作	说明
`express_emotion`	表达情绪（参数：情绪-快乐/悲伤/好奇/惊讶/困惑）
`perform_gesture`	执行手势（参数：手势-问候/是/否/思考/庆祝）

相机

操作	说明
`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": {}}
])

有关命令序列的更多详细信息，请参见序列_命令.md.

与MCP支持的客户端一起使用

最简单的方法是让manager CLI为您编写配置：

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

要手动完成，请将此添加到客户端的配置文件中（JSON同样适用于 Claude桌面、Claude代码和光标——见下面的位置）：

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

配置文件位置：

克劳德桌面版 --macOS： ~/Library/Application Support/Claude/claude_desktop_config.json; Linux： ~/.config/Claude/claude_desktop_config.json; 窗户： %APPDATA%\Claude\claude_desktop_config.json
克劳德代码 --项目： ./.mcp.json；用户： ~/.claude.json
光标 --项目： ./.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

添加新工具

在中创建Python脚本 tools_repository/scripts/my_tool.py:

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文件是否有效以及脚本文件是否存在。

资源

许可证

此项目根据MIT许可证获得许可，包括此存储库中的对话和听力应用程序，并且不扩展到Reachy Mini Daemon。

贡献

欢迎投稿！请随时提交问题或拉取请求。

支持

关于以下问题：

此MCP服务器：在此存储库中打开一个问题
Reachy迷你机器人：参观 Reachy Mini GitHub问题

学分

内置于 FastMCP 马文
为了 Reachy Mini Pollen Robotics&拥抱脸
跟随模型上下文协议规格