# roborock-mcp

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

## 功能

通过 MCP 协议提供 10 个只读查询工具：

| 工具 | 说明 |
|------|------|
| `get_devices` | 列出所有设备（名称、型号、固件版本） |
| `get_status` | 设备实时状态（电量、吸力、拖布湿度、错误码等） |
| `get_rooms` | 房间列表（ID 与名称映射） |
| `get_maps` | 地图概览（地图列表、当前地图） |
| `get_map_content` | 地图内容（机器人位置、充电座位置） |
| `get_home` | 家庭完整布局（所有地图的房间信息） |
| `get_clean_summary` | 清洁历史统计（总时长、面积、次数） |
| `get_consumables` | 耗材状态（主刷、边刷、滤网工作时长） |
| `get_dnd` | 勿扰模式设置 |
| `get_sound_volume` | 音量设置 |

支持多设备，通过设备名称模糊匹配选择目标设备。

## 安装使用

### 通过 uvx（推荐）

**1. 首次认证**

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

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

**2. 配置 Claude Code**

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

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

### 更新

```bash
uvx --refresh roborock-mcp
```

### 开发模式

```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)）
