roborock-mcp 0.5.0

让 Claude 控制石头扫地机 - MCP 服务器

roborock-mcp

MCP 服务器，让 Claude 控制石头扫地机。

功能

通过 MCP 协议提供 13 个工具，支持多设备（通过设备名称模糊匹配选择目标设备）。

查询工具（3 个）

工具	说明
get_devices	列出所有设备（名称、型号、DUID、固件版本），走云端 API
get_status	设备精简状态（走 MQTT 并行查询 8 个 trait），每个字段返回 {"value": x, "description": "..."} 结构。包含：实时状态（电量/吸力/清洁进度/基座/错误码等）、勿扰模式、清洁统计、音量、房间列表、地图列表、耗材寿命
get_map_content	地图元数据（机器人位置、充电座位置），走 MQTT 拉取，数据量较大

控制工具（10 个）

工具	说明
start_clean	开始清洁（全屋或指定房间，支持重复遍数）
stop_clean	停止清洁
pause_clean	暂停清洁
resume_clean	恢复暂停的清洁任务
go_home	回充电座
find_robot	发出声音定位机器人
dock_action	基座操作（集尘/洗拖布）
set_volume	调节语音音量（0-100）
get_routines	列出智能场景，走云端 API
execute_routine	执行智能场景

安装使用

前置：安装 uv

本项目通过 uvx 运行，需要先安装 uv：

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后终端输入 uvx --version 验证。

通过 uvx（推荐）

1. 首次认证

uvx roborock-mcp auth

按提示输入 Roborock 账户邮箱和验证码，认证信息保存在 ~/.cache/roborock-mcp/。

2. 配置 Claude Code

在项目目录创建 .mcp.json：

{
  "mcpServers": {
    "roborock": {
      "command": "uvx",
      "args": ["roborock-mcp@latest"]
    }
  }
}

开发模式

# 需要先 clone python-roborock 到 ./python-roborock/
uv pip install -e .
python -m roborock_mcp         # 启动 server
python -m roborock_mcp auth    # 认证

要求

• Python >= 3.12
• Roborock 账户（国际版，邮箱注册）

许可证

GPL-3.0-only（由于 vendoring 了 python-roborock）