vitruvian-roborock

Autonomous agent control and real-time telemetry for Roborock vacuums. Check on and control your vacuum from a terminal (rrctl), from an AI agent (Antigravity and Claude Code), or from a live map in your browser.

Architecture

One lightweight local process, the daemon, manages the single authenticated session with the vacuum (over local LAN or cloud MQTT), protecting device connection quotas. The CLI, MCP tools, and live dashboard communicate securely with the daemon over local loopback.

flowchart LR
    cli["rrctl (CLI)"] --> daemon
    mcp["FastMCP Server (Agents)"] --> daemon
    web["Live Dashboard (Browser)"] --> daemon
    daemon["Daemon 127.0.0.1:8765"] -- "Local LAN / Cloud Session" --> vacuum["Roborock Vacuum"]

Quick Installation

You need uv. The package is on PyPI, and the plugins fetch and run it themselves with uvx, so there is nothing to install first.

Claude Code:

claude plugin marketplace add VitruvianSoftware/mcp-roborock
claude plugin install vitruvian-roborock

Antigravity:

agy plugin install https://github.com/VitruvianSoftware/mcp-roborock

Just the CLI, rrctl, without an agent:

uv tool install vitruvian-roborock

Quick Start

rrctl setup        # Log in with your Roborock account (email verification code)
rrctl status       # Display live vacuum state, battery, and rooms
rrctl dashboard    # Open the real-time visual map in your browser

Command Reference

Agent Capabilities & Skills

When installed as a plugin, your AI agent automatically gains two specialized skills and seven FastMCP tools:

• Skills:
  • roborock-control: Natural language cleaning, targeted room dispatch, docking, and mop washing.
  • roborock-setup: First-time authentication flow directly inside the conversation.
• FastMCP Tools:
  • get_status: Live status, battery, active errors, and room names.
  • start_clean: Start cleaning (full floor plan).
  • control: Pause, resume, stop, or find the vacuum.
  • return_to_dock: Return to the Ultra dock.
  • wash_mop: Trigger automatic mop washing on Ultra docks.
  • get_map: Fetch real-time rendered floor map with vacuum trajectory.
  • setup_login: Authenticate with Roborock cloud.

Documentation

• Detailed Installation & User Guide
• Architecture & Security Model