roborock-mcp

MCP server for Roborock vacuums, built on python-roborock. Ask your AI assistant for the vacuum's status, a labelled map of your home, or to clean only the kitchen.

Unofficial project, not affiliated with Roborock.

Tools

Supported: vacuums that use Roborock's V1 protocol (S, Q5, Q7 Max series and similar). Other models show up in list_devices but the other tools return "not supported yet".

Related MCP server: Roborock MCP Server

Setup

Needs uv and git. uv downloads Python 3.12+ if you do not have it.

1. Log in once. Roborock sends a code to your email; type it in:

   uvx --from git+https://github.com/anilsrml/roborock-mcp roborock login --email you@example.com

   This writes your token to ~/.roborock. Keep that file private (chmod 600 ~/.roborock).

2. Add the server to your MCP client.

   Claude Code:

   claude mcp add roborock -s user -- uvx --from git+https://github.com/anilsrml/roborock-mcp roborock-mcp

   Claude Desktop, Cursor and other clients (JSON config):

   {
     "mcpServers": {
       "roborock": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/anilsrml/roborock-mcp", "roborock-mcp"]
       }
     }
   }

3. Restart your MCP client and ask in plain language:

   • "Is my vacuum charging? How much battery does it have?"

   • "Show me the map of my home."

   • "Clean only the kitchen and the living room."

   • "Pause the vacuum." / "Send it back to the dock."

How it works

flowchart LR
    A[AI assistant] -- MCP stdio --> S[roborock-mcp]
    S -- reads --> L["~/.roborock<br/>(login token)"]
    S -- python-roborock --> C[Roborock cloud]
    S -- "python-roborock<br/>(local network or MQTT)" --> V[Your vacuum]

1. roborock login (from python-roborock) logs in with the email code and saves your token to ~/.roborock. There is no password; the server only reads this token.

2. On the first tool call the server reads that file and asks the Roborock cloud for your home: devices, rooms, local keys. It saves this to ~/.roborock-mcp.cache, because the cloud allows only 5 of these requests per hour.

3. Each tool call goes to the vacuum through python-roborock, which picks the connection itself: your local network when it can reach the vacuum, otherwise Roborock's MQTT cloud.

4. Rooms:

   • get_map draws the map as a PNG and writes each room's name on it, so you can see which names to use.

   • start_cleaning with rooms turns those names into the vacuum's room ids and starts a room cleaning.

Development

git clone https://github.com/anilsrml/roborock-mcp.git
cd roborock-mcp
uv run pytest

License

MIT