Metadata-Version: 2.4
Name: roborock-mcp
Version: 0.4.3
Summary: 让 Claude 控制石头扫地机 - MCP 服务器
License-Expression: GPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: aiohttp<4,>=3.8.2
Requires-Dist: aiomqtt<3,>=2.5.0
Requires-Dist: certifi
Requires-Dist: click-shell~=2.1
Requires-Dist: click>=8
Requires-Dist: construct<3,>=2.10.57
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: paho-mqtt<3.0.0,>=1.6.1
Requires-Dist: pycryptodomex~=3.18; sys_platform == 'darwin'
Requires-Dist: pycryptodome~=3.18
Requires-Dist: pyrate-limiter<5,>=4.0.0
Requires-Dist: vacuum-map-parser-roborock
Description-Content-Type: text/markdown

# roborock-mcp

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

## 功能

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

### 查询工具（3 个）

| 工具 | 说明 |
|------|------|
| `get_devices` | 列出所有设备（名称、型号、DUID、固件版本），走云端 API |
| `get_status` | 设备全量状态（走 MQTT 并行查询 10 个 trait）：实时状态 60+ 字段、勿扰模式、清洁统计、音量、房间列表、地图列表、耗材、家庭布局、网络信息、设备特性标志 90+ 布尔值 |
| `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"]
    }
  }
}
```

### 更新

```bash
uvx --reinstall 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)）
