米家 MCP Server

中文文档 | English

mijiaAPI 3.x 기반의 제품화된 米家 MCP 서비스입니다. 클라이언트가 더 이상 did, siid/piid/aiid 같은 프로토콜 세부 사항을 먼저 이해할 필요 없이, '가정, 방, 기기 이름, 시나리오 이름'을 우선적으로 고려하여 더 자연스러운 조회 및 제어 기능을 제공합니다.

이 버전이 해결하는 문제

• AI 클라이언트 지향: 안정적이고 명확한 제품 수준 도구를 우선 노출하고, 하위 프로토콜 필드 대신 사용

• 실제 가정 시나리오 지향: 가정과 방을 먼저 확인하고, 기기를 찾은 다음 제어 실행

• MCP 표준 지향: 도구는 구조화된 결과를 반환하며, 서비스 상태와 로그인 상태는 클라이언트가 직접 소비 가능

• 확장 지향: 표준 능력 schema, 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. QR 스캔 완료 후 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 클라이언트 구성 예시

poetry run 대신 가상 환경의 Python을 직접 사용하는 것을 권장합니다.

{
  "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参数个数不匹配 오류를 보고합니다. 반드시 _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": "客厅"
  }
}

능력 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 서비스 외에도 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를 참조하세요.