shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

xiaoi

小爱音箱语音通知工具，支持通过CLI/TUI/MCP/Webhook向小爱音箱发送语音通知，提供多音箱路由、Docker部署和PM2常驻服务。

article

README

🚀 小爱音箱语音通知工具

小爱音箱语音通知工具可通过 CLI / TUI / MCP / Webhook 向小爱音箱发送语音通知，为用户提供便捷的语音通知服务。

🚀 快速开始

你可以通过以下步骤快速使用小爱音箱语音通知工具：

  1. 安装工具（全局安装或从源码安装）。
  2. 完成配置（自动创建或手动配置）。
  3. 根据需求选择 TUI 交互界面、CLI 命令、MCP Server 或 Webhook 服务等方式使用。

✨ 主要特性

  • TUI 交互界面：可配置账号、发送通知、管理 Webhook/PM2。
  • CLI 命令：适用于脚本/自动化场景。
  • MCP Server：可供 Codex/Cursor/VS Code 等 AI 编程助手调用。
  • Webhook 服务：提供 HTTP 接口，便于第三方系统集成。
  • 多音箱路由：支持维护音箱列表、设置默认音箱、按请求 did 临时覆盖。
  • PM2 常驻：可一键让 Webhook 在后台运行，无需挂着终端。

📦 安装指南

全局安装（推荐）

# npm
npm i -g xiaoii

# 或 pnpm
pnpm add -g xiaoii

安装后可在任何目录使用 xiaoi 和 xiaoi-mcp 命令。

从源码安装

git clone https://github.com/xvhuan/xiaoi.git
cd xiaoi

# npm
npm i
npm link

# 或 pnpm
pnpm install
pnpm link --global

💻 使用示例

基础用法

TUI 交互界面

xiaoi

CLI 命令

# 发送语音通知
xiaoi tts "代码编译完成"
xiaoi tts 部署已完成，请查看

# 设置音量
xiaoi volume 30

# 发送 MiOT 指令（可选 did）
xiaoi command 3 1 "[]"
xiaoi command 3 1 '[{"piid":1,"value":true}]' --did 客厅小爱

# 读取 MiOT 属性（可选 did）
xiaoi getprop 3 1 --did 客厅小爱

# 检查连接状态
xiaoi status

# 帮助
xiaoi help

高级用法

MCP Server（AI 编程助手集成）

需要先全局安装并运行 xiaoi 完成账号配置。

VS Code / Cursor（JSON）

在项目中创建 .vscode/mcp.json：

{
  "servers": {
    "xiaoi-voice-notify": {
      "type": "stdio",
      "command": "xiaoi-mcp"
    }
  }
}
Codex CLI（TOML）
[mcp_servers.xiaoi-voice-notify]
command = "xiaoi-mcp"

Webhook 服务（HTTP 接口）

当配置了 webhook.token 时，请在请求中携带请求头：

  • Authorization: Bearer <token>
  • 或 X-Xiaoi-Token: <token> 也可在请求体里传 did 指定本次目标音箱；不传时按默认优先级自动路由。
# 发送语音通知（可选 did 指定目标音箱）
curl -X POST http://localhost:51666/webhook/tts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"text":"你好，世界","did":"客厅小爱"}'

# 播放音频（可选 did）
curl -X POST http://localhost:51666/webhook/audio \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"url":"https://example.com/audio.mp3","did":"卧室小爱"}'

# 设置音量（可选 did）
curl -X POST http://localhost:51666/webhook/volume \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"volume":50,"did":"客厅小爱"}'

# 发送 MiOT 指令（可选 did）
curl -X POST http://localhost:51666/webhook/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"siid":3,"aiid":1,"params":[],"did":"客厅小爱"}'

Webhook 常驻（PM2 一键启动）

# 一键常驻启动（后台运行）
xiaoi pm2 start

# 一键部署（start + save）
xiaoi pm2 deploy

# 查看状态
xiaoi pm2 status

# 查看 pm2 进程日志（stdout/stderr）
xiaoi pm2 logs 200

# 查看 Webhook 日志文件（~/.xiaoi/log/webhook.log 等）
xiaoi pm2 webhook-log 200

# 开关公网访问（修改 webhook.host）
xiaoi pm2 public on
xiaoi pm2 public off

# 停止/删除
xiaoi pm2 stop
xiaoi pm2 delete

# 保存进程列表（配合 pm2 startup 可实现开机自启）
xiaoi pm2 save

# 生成开机自启命令（通常需要管理员/Root 权限）
xiaoi pm2 startup

Docker 部署（容器化 Webhook）

快速开始（直接拉镜像，不用 clone）
# 拉取镜像
docker pull iusy/xiaoi:latest

# 一行启动
docker run -d \
  --name xiaoi-webhook \
  --restart unless-stopped \
  -p 51666:51666 \
  -e XIAOI_USER_ID=你的小米ID \
  -e XIAOI_PASS_TOKEN=你的passToken \
  -e XIAOI_DID=你的音箱名称 \
  -e XIAOI_DEFAULT_DID=默认音箱did \
  -e XIAOI_TOKEN=你的Webhook鉴权Token \
  iusy/xiaoi:latest
或者用 Docker Compose
# 1. 下载 docker-compose.yml 和 .env 模板
curl -O https://raw.githubusercontent.com/xvhuan/xiaoi/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/xvhuan/xiaoi/main/.env.example

# 2. 编辑 .env，填入你的信息
#    XIAOI_USER_ID、XIAOI_PASS_TOKEN、XIAOI_DID（可选 XIAOI_DEFAULT_DID）

# 3. 一键启动
docker-compose up -d

📚 详细文档

配置

自动创建（安装/首次运行）

安装完成或首次执行 xiaoi 时，会自动创建：

  • 目录：~/.xiaoi/（Windows 为 %USERPROFILE%\.xiaoi\）
  • 配置：~/.xiaoi/config.json（空模板）

手动配置

编辑 ~/.xiaoi/config.json：

{
    "speaker": {
        "userId": "你的小米ID（数字，不是手机号）",
        "password": "你的密码（不推荐）",
        "passToken": "你的passToken（推荐）",
        "did": "音箱在米家中的名称",
        "defaultDid": "默认音箱 did（可选）",
        "speakers": [
            {
                "did": "音箱 did",
                "name": "客厅小爱",
                "model": "lx04",
                "enabled": true
            }
        ],
        "ttsMode": "auto",
        "verboseLog": false,
        "ttsFallbackCommand": [5, 1],
        "ttsFallbackCommands": {
            "oh2p": [7, 3],
            "oh2": [5, 3],
            "lx06": [5, 1],
            "s12": [5, 1],
            "l15a": [7, 3],
            "lx5a": [5, 1],
            "lx05": [5, 1],
            "x10a": [7, 3],
            "l17a": [7, 3],
            "l06a": [5, 1],
            "lx01": [5, 1],
            "l05b": [5, 3],
            "l05c": [5, 3],
            "l09a": [3, 1],
            "lx04": [5, 1],
            "asx4b": [5, 3],
            "x6a": [7, 3],
            "x08e": [7, 3],
            "x8f": [7, 3]
        }
    },
    "webhook": {
        "port": 51666,
        "host": "localhost",
        "token": "",
        "logFile": "log/webhook.log"
    },
    "mcp": {
        "logFile": "log/mcp_server.log"
    }
}

配置文件查找优先级：

  1. ~/.xiaoi/config.json
  2. （兜底）安装目录/项目目录下的 config.json

字段说明（常用）： | 字段 | 说明 | |------|------| | speaker.userId | 小米 ID（数字，在小米账号个人信息中查看） | | speaker.password | 小米账号密码（可能因安全验证失败） | | speaker.passToken | passToken（推荐） | | speaker.did | 兼容字段（旧版本默认设备）；新版本会与 defaultDid 同步 | | speaker.defaultDid | 默认音箱 did（未在请求体传 did 时优先使用） | | speaker.speakers | 已添加音箱列表（did/name/model/enabled） | | speaker.ttsMode | TTS 链路模式：auto（先 ttscmd 后默认）、command（仅 ttscmd）、default（仅默认链路） | | speaker.verboseLog | 详细日志开关（true/false），控制是否打印链路执行细节 | | speaker.ttsFallbackCommand | 默认 ttscmd（默认 [5,1]，优先调用） | | speaker.ttsFallbackCommands | 按型号覆盖 ttscmd（如 lx04:[5,1]、l09a:[3,1]） | | webhook.host | 监听地址；需要外网访问可设置为 0.0.0.0（注意安全） | | webhook.port | Webhook 端口 | | webhook.token | Webhook 鉴权 Token（可选；常驻 Webhook 如果留空会自动生成并写回配置） |

Webhook 默认音箱优先级：

  1. speaker.defaultDid
  2. XIAOI_DEFAULT_DID（环境变量）
  3. speaker.did（兼容字段）

请求体显式传 did 时，did 必须在 speaker.speakers 中且 enabled=true，否则返回 400。

提示：在 TUI 的「账号设置」里可切换 TTS 模式、修改默认/机型 ttscmd、开关详细日志；在「连接测试」里可手动输入临时 ttscmd 与临时模式进行调试。

推荐使用 passToken 登录。passToken 获取参考：migpt-next/issues/4

项目结构

xiaoi/
├── bin/
│   └── xiaoi.js              # CLI + TUI 入口
├── lib/
│   ├── config.js             # 用户目录配置管理（自动生成 ~/.xiaoi/config.json）
│   ├── speaker.js            # 核心模块（直连音箱 API）
│   ├── tui.js                # TUI 交互界面
│   ├── webhook_server.js     # 常驻 Webhook 服务入口（可配合 PM2）
│   └── pm2.js                # PM2 一键管理封装
├── mcp_server.js             # MCP Server
├── config.example.json       # 配置模板
├── Dockerfile                # Docker 镜像构建
├── docker-compose.yml        # Docker Compose 编排
├── docker-entrypoint.sh      # 容器启动入口脚本
├── .env.example              # Docker 环境变量模板
└── README.md

常见问题

登录失败怎么办？

  1. 确认 userId 是小米 ID（数字），不是手机号或邮箱。
  2. 推荐使用 passToken 代替密码登录。
  3. passToken 获取参考：migpt-next/issues/4。

找不到设备？

  • 确认 did 与米家 App 中音箱名称完全一致。

致谢

本项目基于 @mi-gpt/next 构建。 https://github.com/idootop/migpt-next

🔧 技术细节

更新日志

v1.0.10 (2026-02-14)

  • 新增多音箱路由能力：支持 speaker.defaultDid 与 speaker.speakers，并兼容旧 speaker.did。
  • Webhook 四个接口支持 body 传 did（tts/audio/volume/command），不传按默认优先级路由。
  • 新增 TUI「音箱列表管理」：支持添加设备、设置默认、启用/禁用、删除。
  • 新增 CLI MiOT 能力：xiaoi command（动作）与 xiaoi getprop（属性读取）。
  • 新增 MCP 工具：do_action 与 get_property，并统一支持可选 did。
  • Docker/文档更新：新增 XIAOI_DEFAULT_DID 与 OH2P（xiaomi.wifispeaker.oh2p）简单 cmd 用例。

v1.0.9 (2026-02-14)

  • 修复 .mi.json（登录凭证缓存）在任意目录执行 CLI 时被写到当前目录的问题，现在固定写入 ~/.xiaoi/ 目录。

v1.0.8 (2026-02-12)

  • 修复 Docker 容器启动失败：移除 pm2-runtime 不支持的 --log-date-format 参数。
  • 修复 Docker 构建失败：npm ci 改为 npm install（兼容 pnpm 项目）。
  • 文档补充 XIAOI_TOKEN 环境变量示例，方便用户自定义 Webhook 鉴权 Token。

v1.0.7 (2026-02-12)

  • 新增 Docker 容器化部署：支持通过环境变量配置，无需手动编辑配置文件，一行命令即可启动 Webhook 服务。
  • 新增 GitHub Actions CI/CD：打 tag 自动发布 npm 包 + 构建推送 Docker 镜像（Docker Hub + GHCR，支持 amd64/arm64 双架构）。
  • 新增 .env.example 环境变量模板，降低 Docker 部署门槛。
  • 容器内使用 PM2（pm2-runtime）管理进程，自动健康检查与重启。

v1.0.6 (2026-02-12)

  • 修复 ttscmd 输入解析错误：[7,3] 不再被误解析为 [0,7]。
  • 优化账号设置显示：默认 ttscmd 未设置时，自动显示当前 did 解析出的设备命令（自动映射）。

v1.0.5 (2026-02-12)

  • 新增 ttscmd 自动映射日志输出：显示 model / match / source / command。
  • 详细日志统一增加 [XIAOI] 前缀，便于在 PM2/控制台过滤检索。

v1.0.4 (2026-02-12)

  • 账号设置页新增按 did 自动解析机型并展示“生效 ttscmd 映射”。
  • 链路调试能力完善：支持手动 cmd、临时链路模式、详细日志开关。

v1.0.3 (2026-02-12)

  • 新增 TTS 链路模式切换：auto / command / default。
  • 连接测试支持手动输入临时 ttscmd 与临时模式，便于现场调试。
  • 新增详细日志开关，可显示/隐藏 ttscmd 与默认链路执行细节。

v1.0.2 (2026-02-11)

  • 调整 TTS 调用顺序：优先 ttscmd(MiOT.doAction)，失败后回退默认 MiNA.play(text)。
  • 内置完整机型 ttsFallbackCommands 映射（含 LX04 等常见型号），并支持用户自定义覆盖。
  • 账号设置新增「查看设备列表并选择 did」，可直接从设备列表一键写回配置，降低 did 填错概率。
  • 配置模板/自动生成配置/README 同步新增 speaker.ttsFallbackCommand 与 speaker.ttsFallbackCommands。
  • 新增主动测试模式：支持分别测试 ttscmd 链路和默认链路（MiNA.play）。
  • 账号设置新增 ttscmd 编辑入口：支持修改默认命令与按机型覆盖命令。
  • 新增 TTS 链路模式：支持 auto / command / default 三种模式，用户可手动切换。
  • 新增详细日志开关：支持显示/隐藏 ttscmd 与默认链路的执行日志。
  • 连接测试支持手动输入临时 ttscmd 与临时链路模式，便于现场调试。

v1.0.1 (2026-02-10)

  • 修复 Windows 下 pm2/npm/npx 探测误判（.cmd shim 导致的 ENOENT/不可执行问题）。
  • 修复 npm v10+ 不支持 npm bin -g 导致的全局 pm2 识别失败（改用 npm prefix -g 回退）。
  • TUI 方向键/小键盘数字选择体验优化（减少重绘卡顿、返回不再二次回车）。
  • Webhook 菜单状态显示优化（区分内嵌/PM2 常驻，避免误导）。
  • 新增：TUI 查看 PM2 日志。
  • 新增：每次启动都会检测更新（可用 XIAOI_NO_UPDATE_CHECK=1 禁用）。

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client