Xiaomi Home MCP Server

中文文档

Control your Xiaomi smart home devices through AI assistants via the Model Context Protocol (MCP).

Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

Features

• Device Discovery — Automatically find all devices in your Xiaomi account
• Status Monitoring — Read power state, brightness, temperature, humidity, battery, lock status
• Device Control — Turn on/off, adjust brightness, color temperature, target temperature
• XiaoAi Speaker — Play/pause music, TTS, volume control, voice commands
• QR Code Login — Scan with Mi Home app, no password needed
• Zero Dependencies Setup — Just two Python files, no pip install required

Quick Start

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• Mi Home app on your phone (for QR code login)

1. Login

uv run --script login.py

A QR code will open in your browser. Scan it with the Mi Home app (Profile → Scan icon in top-right corner).

Tokens are saved to ~/.xiaomi-mcp/tokens.json with 600 permissions.

2. Connect to Claude Code

claude mcp add xiaomi-home -- uv run --script /path/to/mcp_server.py

That’s it! Now you can talk to your devices:

“Turn on the lamp” “What’s the room temperature?” “Is the door locked?” “Set brightness to 50%” “Play some music”

2a. Connect to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "xiaomi-home": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/mcp_server.py"]
    }
  }
}

Available Tools

Supported Devices

The server auto-detects device types by model prefix:

Note: MIoT spec properties (siid/piid) vary by model. The built-in mappings cover common models. If your device returns incorrect values, you may need to look up the correct spec at miot-spec.com and adjust the MIOT_PROPS dict in mcp_server.py.

Token Management

# Check if token is still valid
uv run --script login.py --check

# Clear cached token
uv run --script login.py --logout

# Re-login
uv run --script login.py

Tokens are long-lived but may expire after weeks/months. If the MCP server starts failing, re-run login.py.

Alternative: Environment Variables

If you prefer not to use the login tool, you can pass credentials directly:

claude mcp add xiaomi-home \
    -e XIAOMI_PASS_TOKEN="your_pass_token" \
    -e XIAOMI_USER_ID="your_user_id" \
    -e XIAOMI_DEVICE_ID="your_device_id" \
    -- uv run --script /path/to/mcp_server.py

To get these values, log in to account.xiaomi.com in your browser and extract passToken, userId, and deviceId from cookies.

How It Works

Mi Home App (scan QR) → login.py → ~/.xiaomi-mcp/tokens.json
                                          ↓
Claude / Cursor ←→ MCP Protocol ←→ mcp_server.py ←→ Xiaomi Cloud API
                                                      (api.io.mi.com)

• Authentication: passToken → serviceToken exchange (auto-refreshed)
• Device Control: MIoT spec protocol (siid/piid) + legacy miio RPC
• Speaker: Dual channel — IoT (control/TTS) + MiNA (volume/status)

License

MIT