Skip to main content
Glama
excellence-wh

home-ai

home-ai

米家 API,使用 TypeScript + Bun 实现,可以用代码、CLI、MCP 直接控制米家设备。

🎉 原 Python 版已全部移植为 Bun + TypeScript(原实现保留在 archive/),公共 API 与命令行用法保持一致。

本仓库是 Do1e/mijia-api 的自主维护分支,替换为 TS/Bun 并重置版本 v0.1.0,许可证仍为 GPL-3.0。

GitHub License: GPL-3.0

要求

  • Bun >= 1.0(运行与测试)

Related MCP server: 米家 MCP Server

安装 / 准备

bun install        # 安装依赖
bun src/cli.ts login   # 扫码登录(认证保存到 ~/.config/mijia-api/auth.json)

快速开始

import { mijiaAPI, mijiaDevice } from "./src/index.ts";

const api = new mijiaAPI();     // 已登录时自动加载认证
if (!api.available) await api.login();

// 通过设备名称控制设备(网络异步,需 await)
const device = await mijiaDevice.create(api, undefined, "我的台灯");
await device.set("on", true);         // 打开设备
await device.set("brightness", 60);   // 设置亮度 60%
const b = await device.get("brightness");
console.log(device.toString());        // 打印全部属性和动作

注:Python 版的 device.on = True 魔法属性因 TS 异步不复刻,改用 await device.set("on", true) / await device.get("on")

CLI 用法

bun src/cli.ts login
bun src/cli.ts -l                                    # 列出所有设备
bun src/cli.ts set --dev_name "台灯" --prop_name "brightness" --value 60
bun src/cli.ts get --dev_name "台灯" --prop_name "on"
bun src/cli.ts action --dev_name "台灯" --action_name toggle
bun src/cli.ts run "打开卧室台灯"                        # 通过小爱音箱
bun src/cli.ts --get_device_info yeelink.light.lamp4  # 无需认证

MCP 用法

# 先登录,然后在 MCP 客户端配置(stdio)中指向:
bun <仓库绝对路径>/src/mcp.ts -p ~/.config/mijia-api/auth.json

提供 13 个工具:list_homes / list_devices / list_scenes / list_consumables / get_device_spec / get_device_properties / set_device_property / run_device_action / run_scene / get_statistics / run_speaker_command / login / login_status。

测试

bun test

密码学层(签名/RC4/nonce/解密)通过 tests/reference.json(Python 生成基准)逐项对照验证。

目录

  • src/ 库本体(apis / devices / cli / mcp / miutils / cookies / errors / logger)

  • tests/ 对照测试

  • archive/ 原 Python 实现(只读参照)

  • docs/ VitePress 文档站

  • skills/SKILL.md agent skill

致谢

开源许可

本项目采用 GPL-3.0 开源许可证。

请注意:GPL-3.0 是具有“强传染性”的开源许可证。 如果您在您的项目中使用、修改或分发本项目的代码 (包括作为库依赖),您的整个项目也必须以 GPL-3.0 或兼容许可证开源发布。

免责声明

  • 本项目仅供学习交流使用,不得用于商业用途,如有侵权请联系删除

  • 用户使用本项目所产生的任何后果,需自行承担风险

  • 开发者不对使用本项目产生的任何直接或间接损失负责

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    C
    maintenance
    MCP server for controlling Xiaomi/Mi Home smart devices via natural language, supporting device listing, property read/write, action calls, and camera snapshots.
    11
    -
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables natural language control of Xiaomi smart home devices through MCP, focusing on homes, rooms, device names, and scenes without requiring protocol details.
    68
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to control Xiaomi Mi Home smart devices through natural language, supporting device listing, property control, actions, and scenes.
    7
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that enables AI agents to control Xiaomi Mi Home smart devices through natural language, with support for listing devices, controlling properties, and running scenes.
    MIT