MijiaPilot

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

미지아 × MCP × AI 에이전트 × HomeKit 전체 브리지 스마트 홈 플랫폼.

감사의 말: 본 프로젝트의 기반은 Do1e/mijia-api (mijiaAPI v3.0+)에서 제공하는 Python SDK를 사용하였으며, 샤오미 클라우드와의 기기 통신, 속성 읽기/쓰기 및 장면 실행에 사용됩니다. 원작자의 오픈 소스 기여에 감사드립니다.

데모

에이전트 데모 인터페이스

에이전트 데모 영상

Related MCP server: Home Controller

주요 기능

웹 관리 인터페이스 — 기기 제어, 홈/장면 관리, 에너지 소비 통계, 자동화 규칙, 다크 모드, 모바일 최적화
RESTful API — JWT 인증, 전체 Swagger 문서 (/api/docs/), 타사 통합 지원
CLI 도구 — mijia-control 명령줄, 로그인, 기기 목록, 속성 읽기/쓰기, 장면 실행 지원
실시간 통신 — SocketIO를 통한 기기 상태 변경 푸시
기기 그룹화/즐겨찾기 — 사용자 지정 그룹 관리 및 자주 사용하는 기기 즐겨찾기
시간 기반 자동화 규칙 — cron, interval, 일출/일몰 등 트리거 방식 지원
에너지 통계 대시보드 — 기기별 에너지 소비 데이터 기록 및 표시 (일/시간 단위)
API 토큰 관리 — 타사 애플리케이션을 위한 액세스 토큰 생성 및 관리
MCP 서버 — 내장 MCP 프로토콜 지원, Claude Code / Hermes Agent 등 AI 에이전트가 직접 호출 가능
HomeKit 브리지 — Apple 홈 앱 및 Siri를 통해 미지아 기기 제어 (조명, 플러그, 센서, 온도 조절기 등 지원)
다중 사용자 & 권한 — 사용자 등록/로그인, 관리자 백엔드, 속도 제한 보호

기술 스택

계층	기술
웹 프레임워크	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/`	QR 코드 연동, 상태 조회, 연동 해제
기기 관리	`/api/devices/`	기기 목록, 속성 읽기/쓰기, 동작 실행, 카메라 스트림
홈 관리	`/api/homes/`	홈 목록, 상세 정보
장면 실행	`/api/scenes/`	장면 목록, 실행
기기 그룹	`/api/groups/`	그룹 CRUD, 즐겨찾기 관리
자동화 규칙	`/api/automations/`	시간 규칙 CRUD, 활성화/비활성화
에너지 통계	`/api/energy/`	에너지 기록, 일/시간/최신 조회
API 토큰	`/api/tokens/`	토큰 관리 (타사 통합)

전체 API 문서: 실행 후 /api/docs/에 접속하세요.

MCP 서버 (AI 에이전트 통합)

내장 MCP 서버는 Claude Code, Hermes Agent, OpenClaw 등 MCP 프로토콜을 지원하는 모든 AI 에이전트가 미지아 기기를 직접 제어할 수 있도록 합니다.

설치

pip install -e ".[mcp]"

설정

먼저 웹 서비스가 실행 중인지 확인하고(python run.py), 토큰을 가져옵니다:

# 方式一：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 브리지 (Apple 홈 & Siri 제어)

HAP-Python을 통해 HomeKit 브리지를 구현하여 iPhone 및 Mac 사용자가 Apple 홈 앱과 Siri에서 미지아 기기를 직접 제어할 수 있습니다.

아키텍처

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

설치

pip install -e ".[homekit]"

Windows 사용자: Bonjour Print Services를 설치하거나 Docker를 사용하여 브리지를 실행해야 합니다.

설정

.env에 추가하거나 환경 변수를 직접 설정하세요:

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

웹 서비스가 실행 중인지 확인하고 JWT 토큰(MCP 서버와 동일한 MIJIA_TOKEN)을 가져옵니다.

실행

# 先启动 Web 服务
python run.py

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

페어링

휴대폰과 컴퓨터가 동일한 로컬 네트워크에 있는지 확인
iPhone → 홈 앱 → 기기 추가 → 터미널에 표시된 QR 코드 스캔 또는 PIN 수동 입력
페어링 성공 후, 기기가 「미지아 스마트 홈」 브리지 형태로 나타납니다.

iPhone 홈 앱 화면

지원되는 기기 유형

HomeKit 유형	미지아 기기	제어 기능
Lightbulb	전구, 스트립 조명	스위치, 밝기, 색온도
Outlet	플러그, 스마트 스위치	스위치
Switch	로봇 청소기, 공기청정기 등	스위치
TemperatureSensor	온습도 센서	온도, 습도 읽기
Thermostat	에어컨 컴패니언, 제습기	스위치, 목표 온도
HeaterCooler	히터	스위치, 목표 온도

기기 매핑 사용자 지정

기기 모델이 내장 규칙에 없는 경우, 브리지는 기기의 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`
Linux / macOS	`venv/bin/mijia-control`

선택 사항: 전역 사용 (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