roborock-cli 0.1.2

Roborock 扫地机 CLI 控制工具

roborock-cli

Roborock 扫地机 CLI 控制工具，也可作为 MCP 服务器使用。

功能

提供 15 个 CLI 命令，支持多设备（通过设备名称模糊匹配选择目标设备）。

查询命令（5 个）

命令	说明
roborock-cli devices	列出所有设备（名称、型号、DUID、固件版本）
roborock-cli status	设备精简状态（电量、清洁进度、耗材、房间列表等）
roborock-cli map	获取地图元数据和图片
roborock-cli routines	列出智能场景
roborock-cli auth	交互式认证（需要 TTY）

控制命令（10 个）

命令	说明
roborock-cli start-clean	开始清洁（全屋或指定房间）
roborock-cli stop-clean	停止清洁
roborock-cli pause-clean	暂停清洁
roborock-cli resume-clean	恢复清洁
roborock-cli go-home	回充电座
roborock-cli find-robot	寻找机器人（发出声音）
roborock-cli dock-action	基座操作（集尘/洗拖布）
roborock-cli set-volume	设置音量（0-100）
roborock-cli set-dnd	设置勿扰模式
roborock-cli 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-cli auth

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

2. 使用 CLI

# 列出设备
roborock-cli devices

# 查看状态
roborock-cli status

# 开始全屋清洁
roborock-cli start-clean

# 开始房间清洁（房间 ID 通过 status 命令获取）
roborock-cli start-clean -s 1 2 3

# 回充电座
roborock-cli go-home

作为 MCP 服务器使用

roborock-cli 也可以作为 MCP 服务器运行，供 Claude Desktop/Code 等客户端使用：

roborock-cli mcp

配置 Claude Code

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

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

开发模式

# 需要先 clone python-roborock 到 ./python-roborock/
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

roborock-cli --help          # CLI 帮助
roborock-cli auth            # 认证
roborock-cli mcp             # 启动 MCP server

输出格式

CLI 命令默认输出 JSON 格式，便于程序解析：

{
  "count": 2,
  "devices": [
    {"name": "客厅扫地机", "duid": "abc123", "model": "roborock.vacuum.a75", "firmware": "02.00.01"},
    {"name": "卧室扫地机", "duid": "def456", "model": "roborock.vacuum.s8", "firmware": "02.00.02"}
  ]
}

错误退出码

退出码	含义
0	成功
1	通用业务错误
2	认证错误（需重新运行 roborock-cli auth）
3	设备错误
4	参数无效
5	内部错误

要求

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

许可证

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