Metadata-Version: 2.4
Name: roborock-mcp
Version: 0.2.8
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 协议提供 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` | 音量设置 |

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

## 安装使用

### 前置：安装 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 roborock-mcp update
```

### 开发模式

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