Mijiaapi MCP

🚀 米家智能控制 MCP 服務器

本項目是一個基於 TypeScript 和 Python 構建的 Model Context Protocol (MCP) 服務器。它整合了 mijiaAPI 所提供的米家智能家居能力，支持掃碼登錄、設備列表查看、設備屬性讀取與設置、場景聯動、耗材查詢以及統計數據獲取等常見操作。

🚀 快速開始

此 MCP 服務器整合了米家 API，支持掃碼登錄、設備列表查看、屬性讀取與設置等常見操作。您可以按照以下步驟進行安裝與構建：

# 安裝 Node 依賴
npm install

# 安裝 Python 依賴（建議在虛擬環境中執行）
pip install -r python_scripts/requirements.txt

# 構建 TypeScript
npm run build

首次使用時，您需要進行掃碼登錄：

1. 準備終端：確保終端可以正常顯示 ANSI 字符（以便展示二維碼）。

2. 執行登錄命令（選擇任意一種）：

   # 方式一：使用 Python 模塊
   python -m mijiaAPI -l
   
   # 方式二：使用 CLI 命令
   mijiaAPI -l
   

3. 終端會打印 ASCII 二維碼，同時輸出一個可訪問的二維碼鏈接。

4. 用米家 APP 掃描二維碼並確認登錄。

5. 認證信息會自動保存到 ~/.config/mijia-api/auth.json（可通過 MIJIA_AUTH_PATH 修改）。

6. 之後調用 MCP 工具會自動複用 Token，除非 Token 過期。

⚠️ 重要提示

若希望在項目目錄下保存認證信息，可在 .env 中設置 MIJIA_AUTH_PATH=./.mijia-api/auth.json。

✨ 主要特性

💡 使用建議

每個工具都支持 use_mock=true，便於在沒有真實賬號時調試。

📦 安裝指南

依賴安裝

# 安裝 Node 依賴
npm install

# 安裝 Python 依賴（建議在虛擬環境中執行）
pip install -r python_scripts/requirements.txt

# 構建 TypeScript
npm run build

首次掃碼登錄

1. 準備終端：確保終端可以正常顯示 ANSI 字符（以便展示二維碼）。

2. 執行登錄命令（選擇任意一種）：

   # 方式一：使用 Python 模塊
   python -m mijiaAPI -l
   
   # 方式二：使用 CLI 命令
   mijiaAPI -l
   

3. 終端會打印 ASCII 二維碼，同時輸出一個可訪問的二維碼鏈接。

4. 用米家 APP 掃描二維碼並確認登錄。

5. 認證信息會自動保存到 ~/.config/mijia-api/auth.json（可通過 MIJIA_AUTH_PATH 修改）。

6. 之後調用 MCP 工具會自動複用 Token，除非 Token 過期。

💻 使用示例

基礎用法

# 以下是一個簡單的獲取設備列表的示例
# 假設已經完成了登錄和環境配置
import mijia_tool

devices = mijia_tool.get_mijia_devices(home_id="your_home_id", include_shared=True)
print(devices)

高級用法

# 以下是一個控制設備屬性的示例
import mijia_tool

# 控制設備屬性
mijia_tool.control_device(device_id="your_device_id", operation="set_property", prop_name="brightness", value=50)

📚 詳細文檔

MCP 配置示例

c:/Users/chenz/AppData/Local/CodeBuddyExtension/Cache/CodeBuddyIDE/CodeBuddy/mcp/settings.json

{
  "mcpServers": {
    "mijia-mcp-server": {
      "command": "node",
      "args": ["c:/Users/chenz/CodeBuddy/20251216173558/dist/index.js"],
      "type": "stdio",
      "env": {
        "PYTHON_PATH": "c:/Users/chenz/CodeBuddy/20251216173558/.venv/Scripts/python.exe",
        "PYTHON_SCRIPT_DIR": "c:/Users/chenz/CodeBuddy/20251216173558/python_scripts",
        "MIJIA_AUTH_PATH": "c:/Users/chenz/.config/mijia-api/auth.json"
      }
    }
  }
}

工具參數參考

get_mijia_devices

• home_id (string, 可選)：指定家庭 ID
• include_shared (boolean, default false)
• use_mock (boolean, 可選)

get_device_status

• device_id 或 device_name（至少一個）
• properties (string[])：需要讀取的屬性列表（如 on, brightness）
• include_metadata (boolean, default true)
• sleep_time (number)：讀取間隔（秒）

control_device

• device_id 或 device_name
• operation：set_property / run_action
• prop_name + value：用於 set_property
• action_name + action_value：用於 run_action
• action_kwargs / params：為動作提供額外參數

list_mijia_scenes

• home_id (string, 可選)

run_mijia_scene

• scene_id (string) — 來自 list_mijia_scenes
• home_id (string)

get_mijia_statistics

• payload：與 api.get_statistics 一致，例如：

{
  "payload": {
    "did": "device_did",
    "key": "7.1",
    "data_type": "stat_month_v3",
    "limit": 6,
    "time_start": 1700000000,
    "time_end": 1702592000
  }
}

get_device_spec

• model (string)：如 yeelink.light.lamp4

其餘工具參數可在 src/index.ts 中查看 JSON Schema。

🔧 技術細節

項目結構

my-mcp-server/
├── src/index.ts                  # MCP 主入口（TypeScript）
├── dist/index.js                 # 構建輸出
├── python_scripts/
│   ├── mijia_helper.py           # 登錄、緩存、API 封裝
│   ├── mijia_tool.py             # action 路由腳本
│   ├── get_mijia_devices.py      # 兼容舊入口（委託給 mijia_tool ）
│   ├── get_device_status.py
│   ├── control_device.py
│   ├── requirements.txt          # Python 依賴
│   └── test_environment.py       # 環境檢測腳本
├── README.md / SETUP_GUIDE.md    # 文檔
└── ...

調試與 Mock 模式

• 通過 .env 或 MCP 配置設置 MIJIA_USE_MOCK=1，即可在沒有真實賬號/設備時返回模擬數據。
• python python_scripts/test_environment.py "{}" 可檢查 Python 依賴狀態。

擴展開發

1. 在 python_scripts/mijia_tool.py 中增加新的 action
2. 在 src/index.ts 中為該 action 註冊一個 MCP 工具
3. 運行 npm run build

📄 許可證

本項目採用 GPL-3.0 開源許可證。

⚠️ 重要提示：GPL-3.0 是具有"強傳染性"的 Copyleft 許可證。

• ✅ 您可以自由使用、修改和分發本項目
• ✅ 您可以將其用於商業目的
• ⚠️ 如果您在項目中使用、修改或分發本代碼（包括作為庫依賴），您的整個項目也必須以 GPL-3.0 或兼容許可證開源發佈
• ⚠️ 您必須公開源代碼並聲明修改內容

詳見 LICENSE 文件。