米家 MCP Server

Documentación en chino | English

Un servicio MCP de 米家 con enfoque de producto, basado en mijiaAPI 3.x. Ya no exige que el cliente comprenda primero los detalles del protocolo como did, siid/piid/aiid, sino que prioriza ofrecer capacidades de consulta y control más naturales orientadas a «hogar, habitación, nombre de dispositivo, nombre de escena».

Qué resuelve esta versión

• Orientado a clientes de IA: expone primero herramientas estables y claras de nivel producto, en lugar de campos de protocolo de bajo nivel

• Orientado a escenarios reales del hogar: primero se ven el hogar y las habitaciones, luego se localiza el dispositivo y después se ejecuta el control

• Orientado al estándar MCP: las herramientas devuelven resultados estructurados; el estado del servicio y el estado de inicio de sesión pueden ser consumidos directamente por el cliente

• Orientado a la extensión: el schema de capacidades estándar, el control basado en perfiles y el modelo de recursos pueden seguir evolucionando

Related MCP server: Xiaomi smart home MCP server

Capacidades actuales

Servicio e inicio de sesión

• get_service_status

• prepare_login

• reconnect_service

• clear_saved_login

• refresh_devices

• get_tool_catalog

• ping

Hogar y dispositivos

• get_home_overview

• list_homes

• list_devices

• get_device

• get_device_status

• get_device_capabilities

Control de dispositivos

• 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

Escenas y consumibles

• list_scenes

• execute_scene

• get_consumable_items

Recursos MCP

• mijia://service

• mijia://homes

• mijia://devices

• mijia://scenes

• mijia://capabilities

• mijia://tooling

Instalación

Se recomienda usar Python 3.10+.

poetry install

Si no usas Poetry:

pip install -r requirements.txt

Inicio

poetry run python mcp_server/mcp_server.py

Probar el handshake:

poetry run python mcp_server/mcp_test.py

Método de inicio de sesión

mijiaAPI 3.x ha eliminado el inicio de sesión con cuenta y contraseña; solo admite el inicio de sesión con código QR.

Cuando se necesita iniciar sesión por primera vez, el servicio:

• Genera una página para el navegador: ~/.miot-mcp/qr.html

• También genera una imagen de código QR: ~/.miot-mcp/qr.png

• Por defecto, abre qr.html con el navegador del sistema como primera opción

• Solo si el navegador no puede abrirse, recurre al visor de imágenes o al código QR en la terminal

La información de autenticación se guarda en:

~/.miot-mcp/auth_data.json

Ruta principal recomendada para iniciar sesión

1. Llama a prepare_login

2. Llama a get_service_status

3. Lee service.qr.page_path o service.qr.image_path

4. Tras completar el escaneo, llama a reconnect_service o directamente a refresh_devices

Estado relacionado con el inicio de sesión

Tanto get_service_status como mijia://service devuelven un estado de inicio de sesión estructurado. Los campos más relevantes incluyen:

• 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

Variables de entorno

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

Notas:

• MIJIA_ENABLE_QR: si se habilita el inicio de sesión con código QR; por defecto true

• MIJIA_QR_OPEN_MODE: configuración avanzada; admite browser / viewer / none; por defecto browser

• MIJIA_LOG_LEVEL: nivel de registro; admite DEBUG / INFO / WARNING / ERROR

Ejemplo de configuración para clientes MCP

Se recomienda usar directamente el Python del entorno virtual, en lugar de 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"
      }
    }
  }
}

Rutas de llamada recomendadas

Para la mayoría de los clientes de IA, se recomienda usar preferentemente este flujo:

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

Si el cliente necesita un enrutamiento más estable y explícito, añade además:

1. list_homes

2. list_devices

3. get_device

4. get_device_capabilities

5. control_device

Descripción de herramientas habituales

prepare_login

Prepara activamente el inicio de sesión con código QR. Por defecto reutiliza la página QR existente; si necesitas volver a pasar por un ciclo de escaneo, puedes pasar force_reauth=true.

get_service_status

Devuelve el estado de conexión del servicio, la ruta del archivo de autenticación, la ruta de registro, la ruta de la página QR y sugerencias para los siguientes pasos.

get_home_overview

Genera una vista general de los dispositivos por hogar y habitación, adecuada para que el cliente comprenda primero la estructura del hogar.

get_device_status

Consulta el estado actual de un único dispositivo, las operaciones disponibles y el siguiente paso recomendado.

get_device_capabilities

Devuelve el schema de capacidades estándar y los elementos de control basados en perfil, adecuado para clientes que necesitan un enrutamiento estable.

control_by_intent

Entrada de control en lenguaje natural. Adecuada para la mayoría de los escenarios cotidianos, por ejemplo, «sube el brillo de la lámpara de escritorio del dormitorio al 30%».

control_device

Entrada de control estructurada y unificada. Adecuada cuando el cliente ya conoce la operación objetivo y los parámetros.

speaker_say

Hace que 小爱音箱 reproduzca por voz cualquier texto (un «pregón»). Adecuado para avisos de finalización de tareas largas, locuciones tipo alarma o para que un altavoz concreto lea un texto.

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

Por qué usar play-text en lugar de execute-text-directive:

小爱音箱 tiene dos acciones relacionadas:

• execute-text-directive — envía el texto a 小爱 como pregunta/instrucción para que lo interprete → activa su respuesta de IA (por ejemplo, «me has dejado sin respuesta»), no es una locución pura

• play-text — reproduce texto puro, con el parámetro único _in=[text], no activa la conversación de IA ← speaker_say usa este

Advertencia: la ruta genérica run_action introduce los parámetros en el campo value, lo que hace que la API en la nube devuelva -704220025 Action参数个数不匹配; es obligatorio usar la forma de kwargs _in (device.run_action('play-text', _in=[text]) → method['in']=[text]).

Modo de línea de comandos (sin necesidad de cliente MCP, se invoca directamente mediante script):

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

Parámetros:

• text: el texto que se va a leer (lenguaje natural)

• --speaker: nombre del altavoz (coincidencia aproximada; si no se pasa, se elige el primer altavoz en línea)

• --quiet: ejecución silenciosa (sin locución por voz)

Ejemplos de uso

Ver el estado del servicio

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

Preparar el inicio de sesión activamente

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

Actualizar la asignación de dispositivos y habitaciones

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

Ver la vista general del hogar

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

Ver el estado de un único dispositivo

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

Ver el schema de capacidades

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

Control en lenguaje natural

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

Control estructurado

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

Ejecutar una escena

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

Límites actuales

Esta versión de MCP se centra en las rutas de control del hogar más comunes:

• Exploración de hogares y habitaciones

• Localización de dispositivos

• Control de capacidades generales

• Exposición del schema de capacidades estándar

• Ejecución de escenas

• Consulta de consumibles

Las capacidades típicas ya cubiertas de forma prioritaria incluyen:

• Encendido/apagado

• Brillo

• Temperatura de color

• Temperatura objetivo

• Modo

• Velocidad del ventilador

• Posición de apertura/cierre

Las capacidades de nivel más bajo y con mayor personalización pueden seguir ampliándose hacia control_device, pero ya no se exponen como forma de uso predeterminada.

Estructura del código

El servicio actual se compone internamente de tres capas principales:

• adapter/ se encarga de la interacción con mijiaAPI, el inicio de sesión, el descubrimiento de dispositivos y la experiencia de inicio de sesión con código QR

• mcp_server/core/ se encarga del encapsulado de resultados, el cálculo de capacidades, el enrutamiento de intenciones y la estandarización

• mcp_server/device_definitions/ y mcp_server/device_resources/ se encargan de la definición de capacidades estándar, la definición de intenciones y el modelo de recursos orientado a producto

Las capacidades y rutas actuales no dependen del descubrimiento automático de plugins, sino que importan explícitamente las tablas de definiciones. Así es más claro y más adecuado para que los clientes de IA realicen llamadas estables.

Plugin de integración DSH (DeepSeek Harness)

Además del servicio MCP, este repositorio incluye un plugin de Cordis para DeepSeek Harness (dsh-plugin/dsh-task-notify), que permite al agente DSH avisar activamente mediante 小爱音箱 + notificación de 飞书 (aviso de finalización de tareas largas):

Instalación del plugin DSH

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

El plugin utiliza speaker_say.py (de este repositorio) para realizar la locución de 小爱. El altavoz predeterminado se puede cambiar con set_notify_state(currentSpeaker, "音箱名"), y el estado se guarda en ~/.dsh/profiles/notify-state.json para persistir entre sesiones.

Para más detalles, consulta dsh-plugin/README.md.