米家 MCP Server

Chinesische Dokumentation | English

Ein produktorientierter 米家 MCP-Dienst auf Basis von mijiaAPI 3.x. Er verlangt vom Client nicht mehr, zuerst die Protokolldetails wie did, siid/piid/aiid zu verstehen, sondern bietet – orientiert an „Zuhause, Raum, Gerätename, Szenenname“ – natürlichere Abfrage- und Steuerungsmöglichkeiten.

Was diese Version löst

• Für AI-Clients: Stabile, klare Produktwerkzeuge werden gegenüber Low-Level-Protokollfeldern bevorzugt

• Für reale Zuhause-Szenarien: Erst Zuhause und Räume ansehen, dann Geräte lokalisieren, dann Steuerung ausführen

• Für den MCP-Standard: Werkzeuge liefern strukturierte Ergebnisse; Dienststatus und Anmeldestatus können direkt vom Client konsumiert werden

• Für Erweiterbarkeit: Standard-Capability-Schema, profilgesteuerte Steuerung und Ressourcenmodell können weiterentwickelt werden

Related MCP server: Xiaomi smart home MCP server

Derzeitige Funktionen

Dienste und Anmeldung

• get_service_status

• prepare_login

• reconnect_service

• clear_saved_login

• refresh_devices

• get_tool_catalog

• ping

Zuhause und Geräte

• get_home_overview

• list_homes

• list_devices

• get_device

• get_device_status

• get_device_capabilities

Gerätesteuerung

• 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

Szenen und Verbrauchsmaterialien

• list_scenes

• execute_scene

• get_consumable_items

MCP-Ressourcen

• mijia://service

• mijia://homes

• mijia://devices

• mijia://scenes

• mijia://capabilities

• mijia://tooling

Installation

Es wird empfohlen, Python 3.10+ zu verwenden.

poetry install

Wenn du Poetry nicht verwendest:

pip install -r requirements.txt

Start

poetry run python mcp_server/mcp_server.py

Teste den Handshake:

poetry run python mcp_server/mcp_test.py

Anmeldung

mijiaAPI 3.x hat die Benutzerkonto-/Passwort-Anmeldung entfernt; unterstützt wird nur noch die QR-Code-Anmeldung.

Wenn zum ersten Mal eine Anmeldung erforderlich ist, geht der Dienst wie folgt vor:

• Erzeugt eine Browser-Seite: ~/.miot-mcp/qr.html

• Erzeugt außerdem ein QR-Code-Bild: ~/.miot-mcp/qr.png

• Öffnet standardmäßig bevorzugt qr.html über den Systembrowser

• Nur wenn der Browser nicht geöffnet werden kann, weicht er auf einen Bildbetrachter oder den QR-Code im Terminal aus

Die Anmeldeinformationen werden gespeichert unter:

~/.miot-mcp/auth_data.json

Empfohlener Hauptanmeldepfad

1. Rufe prepare_login auf

2. Rufe get_service_status auf

3. Lies service.qr.page_path oder service.qr.image_path

4. Rufe nach dem Scannen reconnect_service auf oder direkt refresh_devices

Anmeldungsbezogener Status

get_service_status und mijia://service liefern beide einen strukturierten Anmeldestatus. Zu den wichtigsten Feldern gehören:

• 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

Umgebungsvariablen

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

Erläuterungen:

• MIJIA_ENABLE_QR: Legt fest, ob die QR-Code-Anmeldung aktiviert ist; Standard ist true

• MIJIA_QR_OPEN_MODE: Erweiterte Konfiguration; unterstützt browser / viewer / none; Standard ist browser

• MIJIA_LOG_LEVEL: Loglevel; unterstützt DEBUG / INFO / WARNING / ERROR

Beispielkonfiguration für MCP-Clients

Es wird empfohlen, das Python aus der virtuellen Umgebung direkt zu verwenden, statt 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"
      }
    }
  }
}

Empfohlener Aufrufpfad

Für die meisten AI-Clients wird empfohlen, folgende Reihenfolge zu bevorzugen:

1. Rufe prepare_login auf

2. Rufe get_service_status auf

3. Rufe refresh_devices auf

4. Rufe get_home_overview auf

5. Rufe get_device_status auf

6. Rufe control_by_intent auf

7. Rufe list_scenes auf

8. Rufe execute_scene auf

Wenn der Client ein stabileres und expliziteres Routing benötigt, ergänze außerdem:

1. Rufe list_homes auf

2. Rufe list_devices auf

3. Rufe get_device auf

4. Rufe get_device_capabilities auf

5. Rufe control_device auf

Beschreibung der gängigen Werkzeuge

prepare_login

Bereitet die QR-Code-Anmeldung aktiv vor. Standardmäßig wird eine vorhandene QR-Code-Seite bevorzugt wiederverwendet; falls du eine weitere Scan-Runde durchführen möchtest, kannst du force_reauth=true übergeben.

get_service_status

Gibt den Dienstverbindungsstatus, den Pfad der Anmeldedatei, den Protokollpfad, den QR-Code-Seitenpfad und eine Empfehlung für die nächsten Schritte zurück.

get_home_overview

Gibt eine Geräteübersicht nach Zuhause und Raum aus – geeignet, damit der Client zuerst die Zuhause-Struktur versteht.

get_device_status

Zeigt den aktuellen Status eines einzelnen Geräts, verfügbare Aktionen und empfohlene nächste Schritte.

get_device_capabilities

Liefert das Standard-Capability-Schema und profilgesteuerte Steuerungsoptionen – geeignet für Clients, die ein stabiles Routing benötigen.

control_by_intent

Steuerungseinstieg über natürliche Sprache. Geeignet für die meisten alltäglichen Szenarien, z. B. „Stelle die Helligkeit der Tischlampe im Schlafzimmer auf 30 %.“

control_device

Einheitlicher, strukturierter Steuerungseinstieg. Geeignet, wenn der Client die Zielaktion und die Parameter bereits kennt.

speaker_say

Lässt den 小爱音箱 beliebigen Text per Sprachausgabe ansagen („Durchsage“). Geeignet für Erinnerungen bei Abschluss langer Aufgaben, Wecker-Ansagen und das Vorlesen von Text durch einen bestimmten Lautsprecher.

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

Warum play-text statt execute-text-directive:

Der 小爱音箱 hat zwei verwandte Aktionen:

• execute-text-directive — sendet den Text als Frage/Befehl an 小爱 zur Verarbeitung → löst eine AI-Antwort aus (z. B. „Da bin ich überfragt“), ist also keine reine Ansage

• play-text — gibt Text rein als Sprache aus, Parameter _in=[text] als einzelner Parameter, löst keinen AI-Dialog aus ← speaker_say verwendet dieses

Stolperfalle: Wenn der allgemeine run_action-Pfad die Parameter in das value-Feld stopft, meldet die Cloud-API -704220025 Action参数个数不匹配. Man muss die _in-Kwargs-Schreibweise verwenden (device.run_action('play-text', _in=[text]) → method['in']=[text]).

Kommandozeilen-Methode (kein MCP-Client nötig, Skript direkt aufrufen):

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

Parameter:

• text: der vorzulesende Text (natürliche Sprache)

• --speaker: Name des Lautsprechers (unscharfe Übereinstimmung; wenn nicht angegeben, wird der erste Online-Lautsprecher gewählt)

• --quiet: stille Ausführung (keine Sprachausgabe)

Anwendungsbeispiele

Dienststatus anzeigen

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

Anmeldung aktiv vorbereiten

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

Geräte- und Raumzuordnung aktualisieren

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

Zuhause-Übersicht anzeigen

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

Status eines einzelnen Geräts anzeigen

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

Capability-Schema anzeigen

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

Steuerung per natürlicher Sprache

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

Strukturierte Steuerung

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

Szene ausführen

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

Aktuelle Grenzen

Die aktuelle MCP-Version konzentriert sich vor allem auf die häufigsten Pfade der Zuhause-Steuerung:

• Durchsuchen von Zuhause und Räumen

• Gerätelokalisierung

• Allgemeine Capability-Steuerung

• Bereitstellung standardisierter Capability-Schemas

• Szenenausführung

• Abfrage von Verbrauchsmaterialien

Die typischen Capabilities, die bereits schwerpunktmäßig abgedeckt werden, umfassen:

• Ein/Aus

• Helligkeit

• Farbtemperatur

• Zieltemperatur

• Modus

• Lüftergeschwindigkeit

• Öffnungs-/Schließposition

Tiefere und stärker anpassbare Fähigkeiten können weiterhin in control_device erweitert werden, werden aber nicht mehr als Standardnutzung nach außen bereitgestellt.

Codestruktur

Intern besteht der Dienst hauptsächlich aus drei Ebenen:

• adapter/ verantwortlich für die Interaktion mit mijiaAPI, Anmeldung, Geräteerkennung und das QR-Code-Anmeldeerlebnis

• mcp_server/core/ verantwortlich für die Kapselung von Ergebnissen, Capability-Berechnung, Intent-Routing und Standardisierung

• mcp_server/device_definitions/ und mcp_server/device_resources/ verantwortlich für Standard-Capability-Definitionen, Intent-Definitionen und das produktorientierte Ressourcenmodell

Die derzeitigen Capabilities und das Routing verlassen sich nicht auf die automatische Plugin-Erkennung, sondern importieren Definitionstabellen explizit. Das ist klarer und besser für stabile Aufrufe durch AI-Clients geeignet.

DSH（DeepSeek Harness）Integrations-Plugin

Zusätzlich zum MCP-Dienst enthält dieses Repository ein Cordis-Plugin für DeepSeek Harness (dsh-plugin/dsh-task-notify), das es DSH-Agenten ermöglicht, aktiv über 小爱音箱 anzusagen + per 飞书 zu benachrichtigen (Erinnerung beim Abschluss langer Aufgaben):

DSH-Plugin installieren

# 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 生效

Das Plugin verwendet speaker_say.py (aus diesem Repository) für die 小爱-Ansage. Der Standard-Lautsprecher kann mit set_notify_state(currentSpeaker, "音箱名") gewechselt werden; der Status wird in ~/.dsh/profiles/notify-state.json gespeichert und über Sitzungen hinweg beibehalten.

Weitere Details findest du unter dsh-plugin/README.md.