米家 MCP Server

中文文档 | English

mijiaAPI 3.x をベースにした製品化された米家 MCP サービスです。クライアントが did、siid/piid/aiid といったプロトコル詳細を事前に理解する必要はなく、「家庭、部屋、デバイス名、シーン名」を優先した、より自然なクエリと制御を提供します。

このバージョンで解決する問題

• AI クライアント向け: 低レベルのプロトコルフィールドではなく、安定した明確な製品レベルのツールを優先的に公開

• 実際の家庭シーン向け: まず家庭と部屋を確認し、次にデバイスを特定し、その後で制御を実行

• MCP 標準向け: ツールは構造化された結果を返し、サービス状態とログイン状態をクライアントが直接利用可能

• 拡張性向け: 標準能力スキーマ、プロファイル駆動制御、リソースモデルは今後も進化可能

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

標準能力スキーマとプロファイル駆動の制御項目を返します。安定したルーティングが必要なクライアントに適しています。

control_by_intent

自然言語による制御エントリです。「寝室のテーブルランプの明るさを 30% に調整して」など、日常的な使用シーンのほとんどに適しています。

control_device

統一された構造化制御エントリです。クライアントが対象の操作とパラメータをすでに把握している場合に適しています。

speaker_say

小愛スピーカーに任意のテキストを音声読み上げさせます（「呼びかけ」）。長時間タスクの完了通知、アラーム形式の読み上げ、指定したスピーカーでのテキスト読み上げに適しています。

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

execute-text-directive ではなく play-text を使う理由:

小愛スピーカーには関連する 2 つのアクションがあります:

• execute-text-directive — テキストを質問/指示として小愛に送信して解析させる → AI の応答（「聞かれても困ります」など）が発生し、純粋な読み上げではない

• play-text — テキストの純粋な再生。パラメータ _in=[text] の単一引数で、AI 対話を発生させない ← speaker_say はこちらを使用

注意: 汎用の run_action パスでパラメータを value フィールドに入れると、クラウド API が -704220025 Action参数个数不匹配 を返します。_in kwargs 形式（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": "客厅"
  }
}

能力スキーマの確認

{
  "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 は、最も一般的な家庭制御パスを重点的にカバーしています:

• 家庭と部屋の閲覧

• デバイスの特定

• 汎用能力制御

• 標準化された能力スキーマの公開

• シーンの実行

• 消耗品の照会

重点的にカバーされている代表的な能力は以下の通りです:

• オン/オフ

• 明るさ

• 色温度

• 目標温度

• モード

• 風速

• 開閉位置

より低レベルで高度なカスタマイズ能力は、引き続き control_device に拡張できますが、デフォルトの使用方法としては外部に公開されません。

コード構造

現在のサービス内部は主に 3 つのレイヤーで構成されています:

• adapter/ mijiaAPI との対話、ログイン、デバイス検出、QR コードログイン体験を担当

• mcp_server/core/ 結果のカプセル化、能力計算、インテントルーティング、標準化を担当

• mcp_server/device_definitions/ と mcp_server/device_resources/ 標準能力定義、インテント定義、製品化されたリソースモデルを担当

現在の能力とルーティングはプラグインの自動検出に依存せず、定義テーブルを明示的にインポートします。これにより明確になり、AI クライアントが安定して呼び出すのにも適しています。

DSH（DeepSeek Harness）統合プラグイン

このリポジトリには、MCP サービスに加えて、DeepSeek Harness 用の Cordis プラグイン（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 を参照してください。