Mijiaapi MCP

🚀 マイMCPサーバー・米家スマートコントロール

このサーバーは TypeScript と Python を用いて構築された Model Context Protocol (MCP) サーバーで、mijiaAPI が提供する米家スマートホームの機能を統合しています。これにより、スキャンログイン、デバイスリスト、属性の読み取りと設定、シーン連動、消耗品の照会、統計データなどの一般的な操作がサポートされています。

🚀 クイックスタート

このサーバーを使うと、TypeScript と Python で構築された MCP サーバーを通じて、米家スマートホームの機能を利用できます。以下に、セットアップと使用方法の概要を示します。

✨ 主な機能

各ツールは use_mock=true をサポートしており、実際のアカウントがない場合でもデバッグが容易です。

🧱 プロジェクト構造

my-mcp-server/
├── src/index.ts                  # MCP のメインエントリー（TypeScript）
├── dist/index.js                 # ビルド出力
├── python_scripts/
│   ├── mijia_helper.py           # ログイン、キャッシュ、API のラッピング
│   ├── mijia_tool.py             # アクションルーティングスクリプト
│   ├── get_mijia_devices.py      # 旧エントリーとの互換性（mijia_tool に委譲）
│   ├── get_device_status.py
│   ├── control_device.py
│   ├── requirements.txt          # Python の依存関係
│   └── test_environment.py       # 環境検出スクリプト
├── README.md / SETUP_GUIDE.md    # ドキュメント
└── ...

📦 インストール

# Node の依存関係をインストール
npm install

# Python の依存関係をインストール（仮想環境で実行することを推奨）
pip install -r python_scripts/requirements.txt

# TypeScript をビルド
npm run build

🔐 初回のスキャンログイン（必須）

1. ターミナルを準備：ANSI 文字を正常に表示できるターミナルを使用してください（QR コードを表示するため）。
2. ログインコマンドを実行（いずれかを選択）：

   # 方法 1：Python モジュールを使用
   python -m mijiaAPI -l
   
   # 方法 2：CLI コマンドを使用
   mijiaAPI -l
   

3. ターミナルに ASCII 形式の QR コードが表示され、アクセス可能な QR コードのリンクも出力されます。
4. 米家アプリで QR コードをスキャンし、ログインを確認してください。
5. 認証情報は自動的に ~/.config/mijia-api/auth.json に保存されます（MIJIA_AUTH_PATH で変更可能）。
6. その後、MCP ツールを呼び出すと、Token が自動的に再利用されます。ただし、Token が期限切れになった場合は再ログインが必要です。

ヒント：プロジェクトディレクトリに認証情報を保存したい場合は、.env で MIJIA_AUTH_PATH=./.mijia-api/auth.json を設定してください。

⚙️ 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, デフォルト false)
• use_mock (boolean, オプション)

get_device_status

• device_id または device_name（少なくとも 1 つ）
• properties (string[])：読み取りたい属性のリスト（例：on, brightness）
• include_metadata (boolean, デフォルト 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 で確認できます。

🧩 デバッグとモックモード

• .env または MCP 設定で MIJIA_USE_MOCK=1 を設定すると、実際のアカウントやデバイスがなくても模擬データが返されます。
• python python_scripts/test_environment.py "{}" で Python の依存関係の状態を確認できます。

🧱 拡張開発

1. python_scripts/mijia_tool.py で新しい action を追加します。
2. src/index.ts でそのアクションに対応する MCP ツールを登録します。
3. npm run build を実行します。

📄 ライセンス

このプロジェクトは GPL-3.0 オープンソースライセンスを採用しています。

⚠️ 重要な注意事項

GPL-3.0 は「強制的な共有性」を持つ Copyleft ライセンスです。

• ✅ このプロジェクトを自由に使用、修正、配布することができます。
• ✅ 商業目的で使用することができます。
• ⚠️ このコードをプロジェクトで使用、修正、または配布する場合（ライブラリとしての依存関係を含む）、あなたのプロジェクト全体も GPL-3.0 または互換性のあるライセンスでオープンソースとして公開する必要があります。
• ⚠️ ソースコードを公開し、変更内容を明記する必要があります。

詳細は LICENSE ファイルを参照してください。