MijiaPilot

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

MCP Server GitHub license Python Version Flask GitHub stars GitHub issues GitHub last commit

米家 × MCP × AI Agent × HomeKit 全桥接智能家居平台。

致谢：本项目底层使用了 Do1e/mijia-api（mijiaAPI v3.0+）提供的 Python SDK，用于与小米云端进行设备通信、属性读写和场景执行。感谢原作者的开源贡献。

演示

Agent 演示界面

Agent 演示视频

Related MCP server: Home Controller

功能特性

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 控制米家设备，支持灯光、插座、传感器、温控器等
多用户 & 权限 — 用户注册登录、管理员后台、限流保护

技术栈

层级	技术
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
代码质量	Ruff (lint + format)
测试	pytest

项目结构

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

快速开始

1. 环境准备

Python 3.10+
MySQL 5.7+

2. 安装

# 克隆本项目
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. 配置

复制 .env.example 为 .env 并填写实际配置：

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. 初始化数据库

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

# 执行迁移
flask db upgrade

5. 启动

python run.py

访问 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/`	能耗记录、日/小时/最新查询
API Token	`/api/tokens/`	令牌管理（第三方集成）

完整 API 文档：启动后访问 /api/docs/。

MCP Server（AI Agent 集成）

内置 MCP Server，支持 Claude Code、Hermes Agent、OpenClaw 等任何兼容 MCP 协议的 AI Agent 直接控制米家设备。

安装

pip install -e ".[mcp]"

配置

首先确保 Web 服务已启动（python run.py），然后获取 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

设置环境变量：

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

Claude Code 中使用

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

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

可用工具

工具	功能
`list_devices`	列出所有设备
`get_device`	查看设备详情与规格
`get_property`	读取设备属性
`set_property`	设置设备属性（控制设备）
`run_action`	执行设备动作
`list_scenes`	列出场景
`run_scene`	执行场景
`list_homes`	列出家庭
`get_home`	查看家庭详情

HomeKit Bridge（Apple 家庭 & Siri 控制）

通过 HAP-Python 实现 HomeKit 桥接，让 iPhone、Mac 用户在 Apple 家庭 App 和 Siri 中直接控制米家设备。

架构

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

安装

pip install -e ".[homekit]"

Windows 用户：需要安装 Bonjour Print Services 或使用 Docker 运行 Bridge。

配置

在 .env 中添加（或直接设置环境变量）：

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

确保 Web 服务已启动并获取 JWT Token（与 MCP Server 相同的 MIJIA_TOKEN）。

启动

# 先启动 Web 服务
python run.py

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

配对

确保手机和电脑在同一局域网
iPhone → 家庭 App → 添加设备 → 扫描终端显示的 QR 码，或手动输入 PIN
配对成功后，设备会以「米家智能家居」桥接器的形式出现

iPhone 家庭 App 效果

支持的设备类型

HomeKit 类型	米家设备	控制能力
Lightbulb	灯泡、灯带	开关、亮度、色温
Outlet	插座、智能开关	开关
Switch	扫地机、净化器等	开关
TemperatureSensor	温湿度传感器	温度、湿度读取
Thermostat	空调伴侣、除湿机	开关、目标温度
HeaterCooler	取暖器	开关、目标温度

设备映射自定义

当你的设备型号不在内置规则中时，Bridge 会自动从设备的 spec_data 推断类型。如果推断不准确，可以创建 homekit_mapping.yaml 自定义映射：

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

可用类别：light、outlet、switch、temperature_sensor、thermostat、heater、camera、ignored

CLI 使用

安装并激活虚拟环境后，可直接使用 mijia-control 命令（无需 Flask 上下文）：

mijia-control --help                           # 查看帮助

也可通过 Flask CLI 调用：flask mijia <command>

跨平台说明： pip install -e ".[dev]" 会自动创建平台对应的可执行入口：

平台	入口路径	说明
Windows	`venv\Scripts\mijia-control.exe`	激活 venv 后直接可用
Linux / macOS	`venv/bin/mijia-control`	激活 venv 后直接可用

可选：全局使用（不激活 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

用户管理

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

设备控制

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

场景 & 家庭

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

开发

# Lint
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

# 运行测试
pytest -v

许可证

本项目基于 GPL-3.0 许可证开源，继承自上游 mijiaAPI 的许可协议。

Xiaomi smart home MCP server