Mijia MCP Server

Chinese Docs | English

A productized Mijia MCP service based on mijiaAPI 3.x. It no longer requires clients to first understand protocol details such as did, siid/piid/aiid; instead, it prioritizes more natural query and control capabilities oriented around "home, room, device name, and scene name".

What This Version Solves

• AI clients: exposes stable, clear product-level tools first, rather than low-level protocol fields

• Real home scenarios: browse homes and rooms first, then locate devices, then execute controls

• MCP standards: tools return structured results, and service status and login status can be consumed directly by clients

• Extensibility: standard capability schemas, profile-driven control, and resource models can keep evolving

Related MCP server: Xiaomi smart home MCP server

Current Capabilities

Service & Login

• get_service_status

• prepare_login

• reconnect_service

• clear_saved_login

• refresh_devices

• get_tool_catalog

• ping

Homes & Devices

• get_home_overview

• list_homes

• list_devices

• get_device

• get_device_status

• get_device_capabilities

Device Control

• control_by_intent

• control_device

• turn_on_device

• turn_off_device

• set_brightness

• set_color_temperature

• set_target_temperature

• set_hvac_mode

• set_fan_speed

• set_cover_position

Scenes & Consumables

• list_scenes

• execute_scene

• get_consumable_items

MCP Resources

• mijia://service

• mijia://homes

• mijia://devices

• mijia://scenes

• mijia://capabilities

• mijia://tooling

Installation

Python 3.10+ is recommended.

poetry install

If you don't use Poetry:

pip install -r requirements.txt

Startup

poetry run python mcp_server/mcp_server.py

Test the handshake:

poetry run python mcp_server/mcp_test.py

Login Methods

mijiaAPI 3.x has removed username/password login and only supports QR code login.

When login is needed for the first time, the service will:

• Generate a browser page: ~/.miot-mcp/qr.html

• Also generate a QR code image: ~/.miot-mcp/qr.png

• By default, open qr.html with the system browser first

• Fall back to an image viewer or an in-terminal QR code only when the browser cannot open it

Authentication information will be saved to:

~/.miot-mcp/auth_data.json

Recommended Primary Login Flow

1. Call prepare_login

2. Call get_service_status

3. Read service.qr.page_path or service.qr.image_path

4. After the scan, call reconnect_service or directly refresh_devices

Login-Related Status

Both get_service_status and mijia://service return structured login status. Key fields include:

• service.connected

• service.has_saved_login

• service.qr.open_mode

• service.qr.page_path

• service.qr.image_path

• service.qr.login_url

• assistant_summary

• next_steps.should_scan_qr

Environment Variables

export MIJIA_ENABLE_QR="true"
export MIJIA_QR_OPEN_MODE="browser"
export MIJIA_LOG_LEVEL="INFO"

Notes:

• MIJIA_ENABLE_QR: whether to enable QR code login; default true

• MIJIA_QR_OPEN_MODE: advanced setting; supports browser / viewer / none; default browser

• MIJIA_LOG_LEVEL: log level; supports DEBUG / INFO / WARNING / ERROR

MCP Client Configuration Example

It is recommended to use the Python in the virtual environment directly, rather than poetry run.

{
  "mcpServers": {
    "mijia": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/miot-mcp/mcp_server/mcp_server.py"
      ],
      "env": {
        "MIJIA_ENABLE_QR": "true",
        "MIJIA_QR_OPEN_MODE": "browser",
        "MIJIA_LOG_LEVEL": "INFO"
      }
    }
  }
}

Recommended Call Flow

For most AI clients, the following order is recommended:

1. prepare_login

2. get_service_status

3. refresh_devices

4. get_home_overview

5. get_device_status

6. control_by_intent

7. list_scenes

8. execute_scene

If the client needs more stable and explicit routing, supplement with:

1. list_homes

2. list_devices

3. get_device

4. get_device_capabilities

5. control_device

Common Tools

prepare_login

Proactively prepares QR code login. By default, it prefers to reuse the existing QR page; if you need to go through a new scan round, pass force_reauth=true.

get_service_status

Returns service connection status, auth file path, log path, QR page path, and next-step suggestions.

get_home_overview

Outputs a device overview by home and room, suitable for clients to understand the home structure first.

get_device_status

Reads a single device's current status, available actions, and recommended next steps.

get_device_capabilities

Returns standard capability schemas and profile-driven control items, suitable for clients that need stable routing.

control_by_intent

Natural-language control entry point. Suitable for most everyday scenarios, e.g., "set the brightness of the bedroom desk lamp to 30%".

control_device

Unified structured control entry point. Suitable when the client already knows the target action and parameters.

speaker_say

Lets a Xiao Ai speaker voice-announce arbitrary text ("shout-out"). Suitable for long-task completion reminders, alarm-style announcements, and having a specific speaker read text.

{
  "name": "speaker_say",
  "arguments": {
    "text": "任务完成啦，图片已生成",
    "speaker_name": "城市之光音响"
  }
}

Why use play-text instead of execute-text-directive:

The Xiao Ai speaker has two related actions:

• execute-text-directive — sends the text to Xiao Ai as a question/command to parse → triggers its AI response (e.g., "you've stumped me"), not a pure announcement

• play-text — pure text playback, with the single parameter _in=[text], does not trigger an AI conversation ← this is what speaker_say uses

Pitfall: the generic run_action path stuffing parameters into the value field causes the cloud API to report -704220025 Action参数个数不匹配; you must use the _in kwargs style (device.run_action('play-text', _in=[text]) → method['in']=[text]).

Command-line mode (no MCP client needed; call directly via script):

python speaker_say.py "任务完成啦" --speaker "城市之光音响"
python speaker_say.py "任务完成啦" --speaker "客厅音箱" --quiet   # 静默（只执行不播报）

Parameters:

• text: the text to read (natural language)

• --speaker: speaker name (fuzzy match; if not provided, the first online speaker is selected)

• --quiet: execute silently (no voice announcement)

Usage Examples

View Service Status

{
  "name": "get_service_status",
  "arguments": {}
}

Proactively Prepare Login

{
  "name": "prepare_login",
  "arguments": {
    "reopen_qr": true
  }
}

Refresh Device & Room Mapping

{
  "name": "refresh_devices",
  "arguments": {}
}

View Home Overview

{
  "name": "get_home_overview",
  "arguments": {}
}

View Single Device Status

{
  "name": "get_device_status",
  "arguments": {
    "device_name": "吸顶灯",
    "room": "客厅"
  }
}

View Capability Schema

{
  "name": "get_device_capabilities",
  "arguments": {
    "device_name": "台灯",
    "room": "卧室"
  }
}

Natural Language Control

{
  "name": "control_by_intent",
  "arguments": {
    "query": "把卧室台灯亮度调到30%"
  }
}

Structured Control

{
  "name": "control_device",
  "arguments": {
    "operation": "set_color_temperature",
    "device_name": "台灯",
    "room": "卧室",
    "value": 4000
  }
}

Execute Scene

{
  "name": "execute_scene",
  "arguments": {
    "scene_name": "回家模式"
  }
}

Current Boundaries

This version of the MCP focuses on the most common home control paths:

• Home and room browsing

• Device locating

• Generic capability control

• Standardized capability schema exposure

• Scene execution

• Consumable queries

Typical capabilities already covered include:

• On/off

• Brightness

• Color temperature

• Target temperature

• Mode

• Fan speed

• Open/close position

Lower-level, more customizable capabilities can still be extended into control_device, but are no longer exposed externally as the default usage approach.

Code Structure

The service mainly has three layers internally:

• adapter/ Handles interaction with mijiaAPI, login, device discovery, and the QR login experience

• mcp_server/core/ Handles result wrapping, capability calculation, intent routing, and standardization

• mcp_server/device_definitions/ and mcp_server/device_resources/ Handle standard capability definitions, intent definitions, and the productized resource model

The current capabilities and routing do not rely on plugin auto-discovery; instead, definition tables are explicitly imported. This is clearer and more suitable for stable invocation by AI clients.

DSH (DeepSeek Harness) Integration Plugin

In addition to the MCP service, this repository also ships a Cordis plugin for DeepSeek Harness (dsh-plugin/dsh-task-notify), letting the DSH agent proactively announce via the Xiao Ai speaker + Feishu notification (long-task completion reminders):

Install DSH Plugin

# 1. 复制到 DSH profiles 的 node_modules
cp -r dsh-plugin/dsh-task-notify C:\Users\<you>\.dsh\profiles\node_modules\@oadank\dsh-task-notify

# 2. 注册到 ~/.dsh/profiles/web/cordis.patch.yml 的 insert 列表
- id: dsh-task-notify
  name: '@oadank/dsh-task-notify'

# 3. 重启 dsh-web 生效

The plugin calls speaker_say.py (in this repository) to perform the Xiao Ai announcement. The default speaker can be switched with set_notify_state(currentSpeaker, "音箱名"), and the state is persisted across sessions in ~/.dsh/profiles/notify-state.json.

For details, see dsh-plugin/README.md.