米家 MCP Server

Китайская документация | English

Продуктовый MCP-сервис 米家 на базе mijiaAPI 3.x. Он больше не требует, чтобы клиент сначала разбирался в деталях протокола вроде did, siid/piid/aiid, а в первую очередь предоставляет более естественные возможности запросов и управления, ориентированные на «дом, комнату, имя устройства, имя сцены».

Что решает эта версия

• Ориентация на AI-клиентов: в первую очередь предоставляются стабильные и понятные продуктовые инструменты, а не низкоуровневые поля протокола.

• Ориентация на реальные домашние сценарии: сначала дом и комнаты, затем поиск устройства, затем управление.

• Ориентация на стандарт MCP: инструменты возвращают структурированные результаты, а состояние сервиса и статус входа могут напрямую потребляться клиентом.

• Ориентация на расширяемость: стандартные схемы возможностей, управление на основе profile и модель ресурсов могут развиваться дальше.

Related MCP server: xiaomi-device-control

Текущие возможности

Сервис и вход

• get_service_status

• prepare_login

• reconnect_service

• clear_saved_login

• refresh_devices

• get_tool_catalog

• ping

Дома и устройства

• get_home_overview

• list_homes

• list_devices

• get_device

• get_device_status

• get_device_capabilities

Управление устройствами

• 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

Сцены и расходные материалы

• list_scenes

• execute_scene

• get_consumable_items

MCP-ресурсы

• mijia://service

• mijia://homes

• mijia://devices

• mijia://scenes

• mijia://capabilities

• mijia://tooling

Установка

Рекомендуется использовать Python 3.10+.

poetry install

Если вы не используете Poetry:

pip install -r requirements.txt

Запуск

poetry run python mcp_server/mcp_server.py

Проверка рукопожатия:

poetry run python mcp_server/mcp_test.py

Способы входа

В mijiaAPI 3.x убран вход по логину и паролю, поддерживается только вход по QR-коду.

При первом запросе входа сервис:

• Создаёт страницу для браузера: ~/.miot-mcp/qr.html

• Одновременно создаёт изображение QR-кода: ~/.miot-mcp/qr.png

• По умолчанию сначала открывает qr.html в системном браузере

• Только если браузер не открылся, переходит к просмотрщику изображений или QR-коду в терминале

Данные аутентификации сохраняются в:

~/.miot-mcp/auth_data.json

Рекомендуемый основной путь входа

1. Вызовите prepare_login

2. Вызовите get_service_status

3. Прочитайте service.qr.page_path или service.qr.image_path

4. После завершения сканирования вызовите reconnect_service или сразу refresh_devices

Статусы, связанные со входом

get_service_status и mijia://service возвращают структурированный статус входа. Ключевые поля:

• 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

Переменные окружения

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

Пояснения:

• MIJIA_ENABLE_QR: включает ли вход по QR-коду, по умолчанию true

• MIJIA_QR_OPEN_MODE: расширенная настройка, поддерживает browser / viewer / none, по умолчанию browser

• MIJIA_LOG_LEVEL: уровень журнала, поддерживает DEBUG / INFO / WARNING / ERROR

Пример конфигурации MCP-клиента

Рекомендуется использовать Python из виртуального окружения, а не 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"
      }
    }
  }
}

Рекомендуемые пути вызовов

Для большинства AI-клиентов рекомендуется использовать в первую очередь так:

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

Если клиенту нужен более стабильный и явный роутинг, дополнительно:

1. list_homes

2. list_devices

3. get_device

4. get_device_capabilities

5. control_device

Описание часто используемых инструментов

prepare_login

Активно готовит вход по QR-коду. По умолчанию сначала переиспользует существующую страницу QR-кода; если нужно заново пройти цикл сканирования, можно передать force_reauth=true.

get_service_status

Возвращает состояние подключения сервиса, путь к файлу аутентификации, путь к журналу, путь к странице QR-кода и рекомендации по следующим шагам.

get_home_overview

Выводит обзор устройств по домам и комнатам, чтобы клиент сначала понял структуру дома.

get_device_status

Позволяет посмотреть текущее состояние устройства, доступные операции и рекомендуемый следующий шаг.

get_device_capabilities

Возвращает стандартную schema возможностей и элементы управления на основе profile, подходит для клиентов, которым нужен стабильный роутинг.

control_by_intent

Вход для управления на естественном языке. Подходит для большинства повседневных сценариев, например «установить яркость настольной лампы в спальне на 30%».

control_device

Единый структурированный вход для управления. Подходит, когда клиент уже знает целевое действие и параметры.

speaker_say

Заставляет колонку 小爱音箱 озвучить произвольный текст («выкрик»). Подходит для напоминаний о завершении длинных задач, озвучивания по типу будильника и чтения текста указанной колонкой.

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

Почему используется play-text, а не execute-text-directive:

У колонки 小爱音箱 есть два связанных действия:

• execute-text-directive — отправляет текст в 小爱 как вопрос/команду для разбора → вызывает AI-ответ (например, «меня поставили в тупик»), а не чистое озвучивание

• play-text — чистое воспроизведение текста, один параметр _in=[text], не запускает AI-диалог ← speaker_say использует именно его

Ловушка: универсальный путь run_action передаёт параметры в поле value, из-за чего облачный API возвращает -704220025 Action参数个数不匹配; необходимо использовать подход с kwargs через _in (device.run_action('play-text', _in=[text]) → method['in']=[text]).

Способ через командную строку (без MCP-клиента, прямой запуск скриптом):

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

Параметры:

• text: текст для озвучивания (естественный язык)

• --speaker: название колонки (нечёткое сопоставление; если не указано, выбирается первая онлайн-колонка)

• --quiet: тихий режим (без голосового воспроизведения)

Примеры использования

Просмотр статуса сервиса

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

Активная подготовка входа

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

Обновление соответствия устройств и комнат

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

Просмотр обзора дома

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

Просмотр состояния отдельного устройства

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

Просмотр schema возможностей

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

Управление на естественном языке

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

Структурированное управление

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

Выполнение сцены

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

Текущие границы

Эта версия MCP в первую очередь покрывает самые распространённые пути управления домом:

• Просмотр домов и комнат

• Поиск устройств

• Управление общими возможностями

• Предоставление стандартизированной schema возможностей

• Выполнение сцен

• Запрос расходных материалов

Уже хорошо покрытые типовые возможности включают:

• Включение/выключение

• Яркость

• Цветовую температуру

• Целевую температуру

• Режим

• Скорость вентилятора

• Положение открытия/закрытия

Более низкоуровневые и более настраиваемые возможности по-прежнему можно расширять через control_device, но они больше не раскрываются наружу как способ использования по умолчанию.

Структура кода

Внутри сервис в основном состоит из трёх уровней:

• adapter/ отвечает за взаимодействие с mijiaAPI, вход, обнаружение устройств и работу с QR-входом

• mcp_server/core/ отвечает за обёртку результатов, вычисление возможностей, маршрутизацию намерений и стандартизацию

• mcp_server/device_definitions/ и mcp_server/device_resources/ отвечают за определения стандартных возможностей, определения намерений и продуктовую модель ресурсов

Текущие возможности и маршрутизация не зависят от автоматического обнаружения плагинов, а явно импортируют таблицы определений. Так понятнее и стабильнее для вызовов AI-клиентами.

DSH (DeepSeek Harness) интеграционный плагин

Помимо MCP-сервиса, этот репозиторий содержит также Cordis-плагин для DeepSeek Harness (dsh-plugin/dsh-task-notify), который позволяет агенту DSH активно озвучивать через колонку 小爱音箱 + отправлять уведомления в 飞书 (напоминание о завершении длинных задач):

Установка плагина 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 生效

Плагин вызывает speaker_say.py (из этого репозитория) для озвучивания через 小爱. Колонку по умолчанию можно переключить через set_notify_state(currentSpeaker, "音箱名"), состояние сохраняется в ~/.dsh/profiles/notify-state.json и остаётся постоянным между сеансами.

Подробное описание см. в dsh-plugin/README.md.