MijiaPilot

中文 | English | 日本語 | 한국어 | Español

Mijia × MCP × KI-Agent × HomeKit – eine vollständige Smart-Home-Brückenplattform.

Danksagung: Dieses Projekt nutzt im Kern das Python-SDK von Do1e/mijia-api (mijiaAPI v3.0+), um mit der Xiaomi-Cloud für die Gerätekommunikation, das Lesen/Schreiben von Attributen und die Szenenausführung zu interagieren. Vielen Dank an den ursprünglichen Autor für den Open-Source-Beitrag.

Demo

Related MCP server: Home Controller

Funktionen

• Web-Verwaltungsoberfläche — Gerätesteuerung, Haus-/Szenenverwaltung, Energiestatistiken, Automatisierungsregeln, Dark Mode, mobile Anpassung

• RESTful API — JWT-Authentifizierung, vollständige Swagger-Dokumentation (/api/docs/), Unterstützung für Drittanbieter-Integrationen

• CLI-Tool — mijia-control Befehlszeile, unterstützt Login, Gerätelisten, Attribut-Lese-/Schreibvorgänge, Szenenausführung

• Echtzeitkommunikation — SocketIO-Push bei Änderungen des Gerätestatus

• Gerätegruppierung/-favoriten — Benutzerdefinierte Gruppierung zur Geräteverwaltung, schnelles Speichern häufig genutzter Geräte

• Zeitgesteuerte Automatisierungsregeln — Unterstützt Cron, Intervalle, Sonnenaufgang/-untergang als Trigger

• Energiestatistik-Dashboard — Aufzeichnung und Anzeige von Energiedaten pro Gerät (tägliche/stündliche Granularität)

• API-Token-Verwaltung — Erstellung und Verwaltung von Zugriffstokens für Drittanbieter-Anwendungen

• MCP-Server — Integrierte MCP-Protokollunterstützung, direkte Aufrufe durch KI-Agenten wie Claude Code / Hermes Agent möglich

• HomeKit-Brücke — Steuerung von Mijia-Geräten über die Apple Home-App und Siri, unterstützt Lampen, Steckdosen, Sensoren, Thermostate usw.

• Multi-User & Berechtigungen — Benutzerregistrierung und -anmeldung, Admin-Backend, Ratenbegrenzung (Rate Limiting)

Tech-Stack

Projektstruktur

├── app/
│   ├── __init__.py          # Flask 应用工厂
│   ├── extensions.py        # 扩展实例（db, jwt, csrf, socketio...）
│   ├── api/                 # REST API 蓝图 (JWT 认证)
│   ├── web/                 # Web UI 蓝图 (Session + CSRF 认证)
│   ├── services/            # 业务逻辑层
│   ├── models/              # SQLAlchemy 数据模型
│   ├── schemas/             # Marshmallow 序列化/校验
│   ├── utils/               # MijiaAPI 适配器、统一响应、装饰器
│   ├── cli/                 # Click CLI 命令
│   └── homekit/             # HomeKit Bridge（Apple 家庭桥接）
├── mcp_server/              # MCP Server（AI Agent 工具）
├── config/                  # Flask 配置（development/testing/production）
├── migrations/              # Alembic 数据库迁移脚本
├── tests/                   # pytest 测试
├── run.py                   # 开发服务器入口
├── docs/                    # 详细文档（HomeKit、API 等）
└── pyproject.toml           # 项目配置 & 依赖

Schnellstart

1. Umgebungsvorbereitung

• Python 3.10+

• MySQL 5.7+

2. Installation

# 克隆本项目
git clone https://github.com/handsomejustin/mijia-control.git
cd mijia-control

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 安装依赖（mijiaAPI 会作为依赖自动安装）
pip install -e ".[dev]"

3. Konfiguration

Kopieren Sie .env.example nach .env und füllen Sie die tatsächliche Konfiguration aus:

cp .env.example .env

FLASK_APP=app:create_app
FLASK_ENV=development
SECRET_KEY=your-secret-key-here
DATABASE_URL=mysql+pymysql://user:password@127.0.0.1:3306/mijia
JWT_SECRET_KEY=your-jwt-secret-key-here
GO2RTC_URL=http://127.0.0.1:1984

4. Datenbank initialisieren

# 创建 MySQL 数据库
mysql -u root -p -e "CREATE DATABASE mijia CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 执行迁移
flask db upgrade

5. Starten

python run.py

Besuchen Sie http://127.0.0.1:5000, registrieren Sie ein Konto und legen Sie los.

API-Übersicht

Vollständige API-Dokumentation: Nach dem Start unter /api/docs/ abrufbar.

MCP-Server (KI-Agenten-Integration)

Integrierter MCP-Server, der die direkte Steuerung von Mijia-Geräten durch jeden MCP-kompatiblen KI-Agenten wie Claude Code, Hermes Agent oder OpenClaw unterstützt.

Installation

pip install -e ".[mcp]"

Konfiguration

Stellen Sie zunächst sicher, dass der Webdienst gestartet ist (python run.py), und rufen Sie dann das Token ab:

# 方式一：CLI 登录（推荐，自动保存 Token）
mijia-control login

# 方式二：API 登录获取
curl -X POST http://127.0.0.1:5000/api/auth/jwt/login \
  -H "Content-Type: application/json" \
  -d '{"username": "你的用户名", "password": "你的密码"}'
# 返回的 access_token 即为 MIJIA_TOKEN

Umgebungsvariablen setzen:

# Linux / macOS
export MIJIA_API_URL=http://127.0.0.1:5000/api
export MIJIA_TOKEN=eyJhbGci...   # 上一步获取的 access_token

# Windows (PowerShell)
$env:MIJIA_API_URL = "http://127.0.0.1:5000/api"
$env:MIJIA_TOKEN = "eyJhbGci..."

# Windows (CMD)
set MIJIA_API_URL=http://127.0.0.1:5000/api
set MIJIA_TOKEN=eyJhbGci...

Verwendung in Claude Code

# 注册 MCP 服务器
claude mcp add mijia -- python -m mcp_server

# 之后在对话中直接使用
# "帮我把客厅的灯关掉"
# "查看所有设备的在线状态"
# "执行回家场景"

Verfügbare Tools

HomeKit-Brücke (Apple Home & Siri-Steuerung)

Implementierung der HomeKit-Brücke über HAP-Python, damit iPhone- und Mac-Benutzer Mijia-Geräte direkt in der Apple Home-App und über Siri steuern können.

Architektur

Apple 家庭 / Siri  →  HomeKit Bridge (HAP-Python)  →  Flask REST API  →  米家设备
                    独立进程，端口 51826                  python run.py

Installation

pip install -e ".[homekit]"

Windows-Benutzer: Sie müssen Bonjour Print Services installieren oder die Brücke in Docker ausführen.

Konfiguration

Fügen Sie dies in .env hinzu (oder setzen Sie die Umgebungsvariablen direkt):

HOMEKIT_ENABLED=true
HOMEKIT_PORT=51826
HOMEKIT_PIN=123-45-678

Stellen Sie sicher, dass der Webdienst gestartet ist und Sie ein JWT-Token erhalten haben (dasselbe MIJIA_TOKEN wie für den MCP-Server).

Starten

# 先启动 Web 服务
python run.py

# 再启动 HomeKit Bridge（另一个终端）
python -m app.homekit

Kopplung

1. Stellen Sie sicher, dass sich Telefon und Computer im selben lokalen Netzwerk befinden.

2. iPhone → Home-App → Gerät hinzufügen → QR-Code scannen, der im Terminal angezeigt wird, oder PIN manuell eingeben.

3. Nach erfolgreicher Kopplung erscheinen die Geräte als „Mijia Smart Home“-Brücke.

iPhone Home-App-Ansicht

Unterstützte Gerätetypen

Benutzerdefinierte Gerätezuordnung

Wenn Ihr Gerätemodell nicht in den integrierten Regeln enthalten ist, leitet die Brücke den Typ automatisch aus den spec_data des Geräts ab. Wenn die Ableitung ungenau ist, können Sie eine homekit_mapping.yaml für benutzerdefinierte Zuordnungen erstellen:

cp homekit_mapping.yaml.example homekit_mapping.yaml

# homekit_mapping.yaml
devices:
  zhimi.airp.mb4a: switch           # 精确 model 匹配
  lumi.sensor_magnet.aq2: ignored   # 忽略不需要的设备

fallback: auto    # auto=智能推断 | switch=全部当开关 | ignore=忽略未知

Verfügbare Kategorien: light, outlet, switch, temperature_sensor, thermostat, heater, camera, ignored

CLI-Verwendung

Nach der Installation und Aktivierung der virtuellen Umgebung können Sie den Befehl mijia-control direkt verwenden (ohne Flask-Kontext):

mijia-control --help                           # 查看帮助

Kann auch über Flask CLI aufgerufen werden: flask mijia <command>

Plattformübergreifende Hinweise: pip install -e ".[dev]" erstellt automatisch die plattformspezifischen ausführbaren Einstiegspunkte:

Optional: Globale Verwendung (ohne venv-Aktivierung)

# Linux / macOS — 创建软链接
sudo ln -s /path/to/mijia-control/venv/bin/mijia-control /usr/local/bin/mijia-control

# Windows — 将以下路径添加到系统 PATH 环境变量
# D:\path\to\mijia-control\venv\Scripts

Benutzerverwaltung

mijia-control login                            # 登录（交互式输入用户名密码）
mijia-control logout                           # 退出登录
mijia-control whoami                           # 查看当前用户
mijia-control xiaomi status                    # 查看小米账号绑定状态
mijia-control xiaomi unlink                    # 解绑小米账号

Gerätesteuerung

mijia-control device list                      # 列出设备
mijia-control device list --home-id <id>       # 按家庭筛选
mijia-control device list --refresh            # 强制刷新设备列表
mijia-control device show <did>                # 查看设备详情
mijia-control device get <did> <prop_name>     # 读取设备属性
mijia-control device set <did> <prop_name> <value>  # 设置设备属性
mijia-control device action <did> <action_name>     # 执行设备动作

Szenen & Häuser

mijia-control scene list                       # 列出场景
mijia-control scene list --refresh             # 强制刷新
mijia-control scene run <scene_id>             # 执行场景
mijia-control home list                        # 列出家庭
mijia-control home show <home_id>              # 查看家庭详情

Entwicklung

# Lint
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

# 运行测试
pytest -v

Lizenz

Dieses Projekt ist unter der GPL-3.0 Lizenz veröffentlicht und übernimmt die Lizenzvereinbarung des Upstream-Projekts mijiaAPI.