# 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](https://docs.astral.sh/uv/)：

**macOS / Linux**

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

**Windows**

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

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

### 通过 uvx（推荐）

**1. 首次认证**

```bash
uvx roborock-mcp auth
```

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

**2. 配置 Claude Code**

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

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

### 开发模式

```bash
# 需要先 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](https://github.com/humbertogontijo/python-roborock)）
