handsomejustin/mijia-control

中文 | English | 日本語 | 한국어 | Español
米家 小米生态 × MCP x CLI × AI Agent × HomeKit 全桥接智能家居平台。
Changelog
v1.0.3 (2026-05-14)
- **fix**: SQLALCHEMY_DATABASE_URI 增加 SQLite 默认值（sqlite:///mijia.db），未设置 DATABASE_URL 时不再崩溃
- **fix**: Werkzeug 3.1+ 安全限制，run.py 添加 allow_unsafe_werkzeug=True 保障开发环境启动
> **升级注意**：如果你之前使用 MySQL，不受影响。SQLite 仅在未配置 DATABASE_URL 时作为 fallback。
> 若从 MySQL 首次切换到 SQLite（或新建 SQLite 数据库），需要执行 flask db upgrade 创建表，
> 并通过 Web 界面或 /api/auth/register 注册用户，再绑定小米账号后方可使用设备控制功能。
v1.0.2 (2026-05-13)
- **fix**: 修复 Jinja2 search 测试不存在导致的 500 错误
v1.0.1
- **feat**: 专属设备控制页模板（灯光、取暖器、空调伴侣、传感器、开关、摄像头）
- **feat**: 通用设备控制页使用共享组件和更好的 UI
v1.0.0
- 初始发布
> **致谢**：本项目底层使用了 Do1e/mijia-api（mijiaAPI v3.0+）提供的 Python SDK，
> 用于与小米云端进行设备通信、属性读写和场景执行。感谢原作者的开源贡献。
演示
功能特性
- **Web 管理界面** — 设备控制、家庭/场景管理、能耗统计、自动化规则、深色模式、移动端适配
- **RESTful API** — JWT 认证，完整的 Swagger 文档（/api/docs/），支持第三方集成
- **CLI 工具** — mijia-control 命令行，支持登录、设备列表、属性读写、场景执行
- **实时通信** — SocketIO 推送设备状态变更
- **设备分组/收藏** — 自定义分组管理设备，快速收藏常用设备
- **定时自动化规则** — 支持 cron、interval、日出/日落等触发方式
- **能耗统计仪表板** — 按设备记录和展示能耗数据（日/小时粒度）
- **API Token 管理** — 为第三方应用创建和管理访问令牌
- **MCP Server** — 内置 MCP 协议支持，Claude Code / Hermes Agent 等 AI Agent 可直接调用
- **HomeKit 桥接** — 通过 Apple 家庭 App 和 Siri 控制米家设备，支持灯光、插座、传感器、温控器等
- **BLE 蓝牙传感器** — PC 蓝牙直连小米 BLE 温湿度计，本地实时数据采集，支持自动化联动
- **多用户 & 权限** — 用户注册登录、管理员后台、限流保护
技术栈
| 层级 | 技术 |
|------|------|
| Web 框架 | Flask 3.0+ |
| ORM & 迁移 | SQLAlchemy + Flask-Migrate (Alembic) |
| 数据库 | MySQL (pymysql) |
| 认证 | Flask-Login (Session) + Flask-JWT-Extended (API) |
| CSRF 保护 | Flask-WTF |
| 限流 | Flask-Limiter |
| 实时通信 | Flask-SocketIO |
| API 文档 | Flasgger (Swagger UI) |
| 序列化/校验 | Marshmallow |
| 米家 SDK | mijiaAPI >= 3.0 |
| MCP 协议 | MCP Python SDK >= 1.6 |
| HomeKit | HAP-Python >= 5.0 |
| BLE 扫描 | bleak >= 0.22 |
| 代码质量 | Ruff (lint + format) |
| 测试 | pytest |
项目结构
快速开始
1. 环境准备
- Python 3.10+
- MySQL 5.7+
2. 安装
3. 配置
复制 .env.example 为 .env 并填写实际配置：
4. 初始化数据库
5. 启动
访问 http://127.0.0.1:5000 ，注册账号后即可使用。
API 概览
| 模块 | 路径前缀 | 说明 |
|------|----------|------|
| 认证 (Session) | /api/auth/ | 注册、登录、登出、修改密码 |
| 认证 (JWT) | /api/auth-jwt/ | JWT 登录、刷新令牌 |
| 小米账号绑定 | /api/xiaomi/ | 二维码绑定、状态查询、解绑 |
| 设备管理 | /api/devices/ | 设备列表、属性读写、动作执行、摄像头流 |
| 家庭管理 | /api/homes/ | 家庭列表、详情 |
| 场景执行 | /api/scenes/ | 场景列表、执行 |
| 设备分组 | /api/groups/ | 分组 CRUD、收藏管理 |
| 自动化规则 | /api/automations/ | 定时规则 CRUD、启用/禁用 |
| 能耗统计 | /api/energy/ | 能耗记录、日/小时/最新查询 |
| BLE 传感器 | /api/ble/ | BLE 设备注册、数据上报、历史查询 |
| API Token | /api/tokens/ | 令牌管理（第三方集成） |
完整 API 文档：启动后访问 /api/docs/。
MCP Server（AI Agent 集成）
内置 MCP Server，支持 Claude Code、Hermes Agent、OpenClaw 等任何兼容 MCP 协议的 AI Agent 直接控制米家设备。
安装
配置
首先确保 Web 服务已启动（python run.py），然后获取 Token：
设置环境变量：
Claude Code 中使用
可用工具
| 工具 | 功能 |
|------|------|
| list_devices | 列出所有设备 |
| get_device | 查看设备详情与规格 |
| get_property | 读取设备属性 |
| set_property | 设置设备属性（控制设备） |
| run_action | 执行设备动作 |
| list_scenes | 列出场景 |
| run_scene | 执行场景 |
| list_homes | 列出家庭 |
| get_home | 查看家庭详情 |
| list_ble_devices | 列出 BLE 传感器设备 |
| get_ble_sensor | 获取 BLE 传感器最新数据 |
| get_ble_readings | 查询 BLE 传感器历史读数 |