roborock-mcp 0.6.2

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

roborock-mcp

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

功能

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

查询工具（4 个）

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

控制工具（10 个）

工具	说明
start_clean	开始清洁（全屋或指定房间，支持重复遍数）
stop_clean	停止清洁
pause_clean	暂停清洁
resume_clean	恢复暂停的清洁任务
go_home	回充电座
find_robot	发出声音定位机器人
dock_action	基座操作（集尘/洗拖布）
set_volume	调节语音音量（0-100）
set_dnd	勿扰模式开关和时间段设置（默认 22:00-08:00）
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    # 认证

环境变量

可选配置；未设置时使用下列默认值。

变量	默认值	说明
ROBOROCK_AUTH_CACHE	~/.cache/roborock-mcp/user_data.json	认证缓存（auth 子命令写入）路径
ROBOROCK_DEVICE_CACHE	~/.cache/roborock-mcp/device_cache.pkl	SDK 设备/家庭元数据磁盘缓存路径
ROBOROCK_SDK_PREFER_CACHE	未启用（等同 false）	为真时 SDK 优先磁盘 pickle，可能跳过云端 get_home_data()，改名/房间等可能与账号不一致；默认假，拉最新 home 并丢弃陈旧 device_features，与实时状态一致。取值：1、true、yes、on（大小写不敏感）。

在 MCP 配置里可为服务增加 "env": { "ROBOROCK_SDK_PREFER_CACHE": "1" } 等字段。

要求

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

许可证

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