MijiaPilot

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

Plataforma de hogar inteligente con puente completo Mijia × MCP × AI Agent × HomeKit.

Agradecimientos: Este proyecto utiliza en su base el SDK de Python proporcionado por Do1e/mijia-api (mijiaAPI v3.0+), utilizado para la comunicación con la nube de Xiaomi, lectura/escritura de atributos y ejecución de escenas. Gracias al autor original por su contribución de código abierto.

Demostración

Related MCP server: Home Controller

Características

• Interfaz de gestión web — Control de dispositivos, gestión de hogar/escenas, estadísticas de consumo energético, reglas de automatización, modo oscuro, adaptación móvil

• API RESTful — Autenticación JWT, documentación Swagger completa (/api/docs/), compatible con integraciones de terceros

• Herramienta CLI — Línea de comandos mijia-control, compatible con inicio de sesión, lista de dispositivos, lectura/escritura de atributos, ejecución de escenas

• Comunicación en tiempo real — Notificaciones SocketIO sobre cambios de estado de dispositivos

• Grupos/Favoritos de dispositivos — Gestión de dispositivos mediante grupos personalizados, acceso rápido a dispositivos frecuentes

• Reglas de automatización programadas — Compatible con disparadores cron, intervalos, amanecer/atardecer, etc.

• Panel de estadísticas de energía — Registro y visualización de datos de consumo por dispositivo (granularidad diaria/horaria)

• Gestión de API Token — Creación y gestión de tokens de acceso para aplicaciones de terceros

• Servidor MCP — Soporte integrado para el protocolo MCP, invocable directamente por agentes de IA como Claude Code / Hermes Agent

• Puente HomeKit — Controla dispositivos Mijia a través de la app Casa de Apple y Siri, compatible con luces, enchufes, sensores, termostatos, etc.

• Multiusuario y permisos — Registro e inicio de sesión de usuarios, panel de administración, protección contra limitación de tasa (rate limiting)

Stack tecnológico

Estructura del proyecto

├── 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           # 项目配置 & 依赖

Inicio rápido

1. Preparación del entorno

• Python 3.10+

• MySQL 5.7+

2. Instalación

# 克隆本项目
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. Configuración

Copie .env.example a .env y rellene la configuración real:

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. Inicialización de la base de datos

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

# 执行迁移
flask db upgrade

5. Inicio

python run.py

Acceda a http://127.0.0.1:5000, regístrese y comience a usarlo.

Resumen de la API

Documentación completa de la API: acceda a /api/docs/ después de iniciar.

Servidor MCP (Integración con Agentes de IA)

Servidor MCP integrado, compatible con Claude Code, Hermes Agent, OpenClaw y cualquier agente de IA compatible con el protocolo MCP para controlar directamente dispositivos Mijia.

Instalación

pip install -e ".[mcp]"

Configuración

Primero asegúrese de que el servicio web esté iniciado (python run.py), luego obtenga el Token:

# 方式一：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

Configure las variables de entorno:

# 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...

Uso en Claude Code

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

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

Herramientas disponibles

Puente HomeKit (Control mediante Apple Casa y Siri)

Implementa el puente HomeKit a través de HAP-Python, permitiendo a los usuarios de iPhone y Mac controlar dispositivos Mijia directamente desde la app Casa de Apple y Siri.

Arquitectura

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

Instalación

pip install -e ".[homekit]"

Usuarios de Windows: Necesitan instalar Bonjour Print Services o usar Docker para ejecutar el puente.

Configuración

Agregue al .env (o configure directamente las variables de entorno):

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

Asegúrese de que el servicio web esté iniciado y obtenga el Token JWT (el mismo MIJIA_TOKEN que para el servidor MCP).

Inicio

# 先启动 Web 服务
python run.py

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

Emparejamiento

1. Asegúrese de que el teléfono y el ordenador estén en la misma red local

2. iPhone → App Casa → Añadir accesorio → Escanee el código QR mostrado en la terminal, o introduzca el PIN manualmente

3. Una vez emparejado, los dispositivos aparecerán como un puente "Hogar inteligente Mijia"

Efecto en la app Casa de iPhone

Tipos de dispositivos compatibles

Personalización de mapeo de dispositivos

Cuando el modelo de su dispositivo no está en las reglas integradas, el puente deducirá automáticamente el tipo a partir de los spec_data del dispositivo. Si la deducción no es precisa, puede crear un archivo homekit_mapping.yaml para personalizar el mapeo:

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=忽略未知

Categorías disponibles: light, outlet, switch, temperature_sensor, thermostat, heater, camera, ignored

Uso de CLI

Tras instalar y activar el entorno virtual, puede usar directamente el comando mijia-control (sin necesidad de contexto Flask):

mijia-control --help                           # 查看帮助

También se puede invocar mediante Flask CLI: flask mijia <command>

Nota multiplataforma: pip install -e ".[dev]" creará automáticamente los ejecutables correspondientes a la plataforma:

Opcional: Uso global (sin activar venv)

# 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

Gestión de usuarios

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

Control de dispositivos

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>     # 执行设备动作

Escenas y hogares

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>              # 查看家庭详情

Desarrollo

# Lint
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

# 运行测试
pytest -v

Licencia

Este proyecto es de código abierto bajo la licencia GPL-3.0, heredada del acuerdo de licencia del proyecto original mijiaAPI.