@zythum02/mijia-api

从 Do1e/mijia-api 移植的 TypeScript 版本

小米米家设备控制工具，提供三种使用方式：

• TypeScript API — 在代码中直接控制设备
• CLI — 命令行操作
• MCP Server — 让 AI 客户端（Claude Desktop、Cline 等）直接控制设备

---

安装

npm install @zythum02/mijia-api
# 或
pnpm add @zythum02/mijia-api
# 或
yarn add @zythum02/mijia-api

---

TypeScript API

登录

首次使用需要通过二维码登录，认证数据会自动持久化：

import { MijiaAPI } from '@zythum02/mijia-api';

const api = new MijiaAPI();
await api.login();  // 终端打印二维码，用米家 APP 扫码

Token 有效期为 30 天，后续启动自动加载。

查询设备

const homes = await api.getHomesList();
const devices = await api.getDevicesList();

读写属性

// 获取亮度
const result = await api.getDevicesProp({
  did: '318289031', siid: 2, piid: 2,
});
console.log(result.value);

// 关灯
await api.setDevicesProp({
  did: '318289031', siid: 2, piid: 1, value: false,
});

高级封装（MijiaDevice）

无需关心 siid/piid：

import { MijiaAPI, MijiaDevice } from '@zythum02/mijia-api';

const api = new MijiaAPI();
const lamp = await MijiaDevice.create(api, { devName: '台灯' });

await lamp.set('brightness', 60);
await lamp.set('on', false);
const brightness = await lamp.get('brightness');

跨平台（浏览器）

API 层无 Node.js 依赖，可在浏览器中使用：

import { MijiaAPI } from '@zythum02/mijia-api';
const api = new MijiaAPI();  // 默认 MemoryCache，数据在内存中

需要持久化时传入 DiskCache：

import { MijiaAPI } from '@zythum02/mijia-api';
import { DiskCache } from '@zythum02/mijia-api/cache/disk-cache';

const api = new MijiaAPI(new DiskCache('/custom/path'));

---

CLI

npx @zythum02/mijia-api <command> [options]

全局选项

选项	说明
--cache-dir <path>	缓存根目录（默认 ~/.config/mijia-api）
-o, --output <format>	输出格式: text / yaml / json（默认 text）

查询类

命令	说明
list-homes	列出所有家庭及房间
list-rooms [--home-id]	列出房间及其设备
list-devices / ls	列出所有设备（含共享）
list-scenes [--home-id]	列出场景
list-consumables [--home-id]	列出耗材

操作类

命令	说明
get --did <id> --prop-name <name>	读取设备属性
set --did <id> --prop-name <name> --value <v>	设置设备属性
run-scene --scene-id <id>	运行场景
device-info --model <model>	查询设备规格

语音类

命令	说明
run <prompt> [--speaker-did] [--quiet]	小爱音箱语音指令

示例

# 登录
npx @zythum02/mijia-api login

# 查看设备
npx @zythum02/mijia-api ls

# YAML / JSON 输出
npx @zythum02/mijia-api ls -o yaml
npx @zythum02/mijia-api ls -o json

# 关灯
npx @zythum02/mijia-api set --did 318289031 --prop-name on --value false

# 语音控制
npx @zythum02/mijia-api run "关掉客厅灯"

# 指定缓存目录
npx @zythum02/mijia-api --cache-dir /data/mijia-cache ls

---

MCP Server

让 AI 客户端直接控制米家设备。作为 MCP Server 运行时，二维码自动通过浏览器打开。

启动

npx @zythum02/mijia-api mcp
# 或指定缓存目录
npx @zythum02/mijia-api mcp --cache-dir /data/mijia-cache

AI 客户端配置

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "mijia-api": {
      "command": "npx",
      "args": [
        "-y",
        "@zythum02/mijia-api",
        "mcp"
      ]
    }
  }
}

Cline / Roo Code

cline_mcp_settings.json 或 roo_mcp_settings.json：

{
  "mcpServers": {
    "mijia-api": {
      "command": "npx",
      "args": [
        "-y",
        "@zythum02/mijia-api",
        "mcp",
        "--cache-dir",
        "/path/to/mijia-cache"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

VS Code 插件（Cline / Continue）

{
  "mcpServers": {
    "mijia-api": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zythum02/mijia-api",
        "mcp"
      ]
    }
  }
}

可用 MCP 工具

工具	功能	参数
login	登录米家账号（浏览器打开二维码）	—
logout	清除认证信息	—
list-homes	列出所有家庭	—
list-rooms	按房间查看设备	homeId?
list-devices	列出所有设备（含共享）	—
list-scenes	列出场景	homeId?
list-consumables	列出耗材	homeId?
get-prop	读取设备属性	did?, devName?, propName
set-prop	设置设备属性	did?, devName?, propName, value
run-scene	运行场景	sceneId, homeId?
device-info	查询设备规格	model
run-speaker	小爱音箱语音指令	prompt, speakerDid?, quiet?

---

设备规格查询

import { getDeviceInfo } from '@zythum02/mijia-api';

const info = await getDeviceInfo('yeelink.light.lamp4');
console.log(info.properties);  // 属性列表
console.log(info.actions);     // 动作列表

结果自动缓存到 ~/.config/mijia-api/device-cache/{model}.json。

---

项目结构

src/
├── index.ts                  # 统一导出（纯 API，无平台依赖）
├── cache/
│   ├── cache.ts              # Cache 接口
│   ├── memory-cache.ts       # 内存缓存（浏览器可用）
│   └── disk-cache.ts         # 磁盘缓存（Node.js）
├── apis/
│   ├── apis.ts               # MijiaAPI — 核心 API
│   └── devices.ts            # MijiaDevice / getDeviceInfo
├── cli.ts                    # CLI 入口
├── mcp.ts                    # MCP Server（createMcpServer）
├── utils/
│   ├── crypto.ts             # 米家 RC4 加解密（纯 JS，无平台依赖）
│   └── errors.ts             # 错误码与异常类
└── version.ts                # 版本号

---

致谢

• Do1e/mijia-api — 原始 Python 版本
• Squachen/micloud — 加解密算法参考
• 米家 APP 网络请求的抓包、加解密与构造的代码笔记
• al-one/hass-xiaomi-miot

开源许可

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

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

免责声明

• 本项目仅供学习交流使用，不得用于商业用途，如有侵权请联系删除
• 用户使用本项目所产生的任何后果，需自行承担风险
• 开发者不对使用本项目产生的任何直接或间接损失负责