Skip to main content
Glama
ganyu123456

mcp-xiaomi-server

by ganyu123456
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MCP Xiaomi Server

为 LLM 大模型提供本地米家设备读取能力的 MCP (Model Context Protocol) Server。通过 python-miio 在局域网内直连米家 WiFi 设备(UDP:54321),读取实时状态(开关、温度、湿度、功率等);并可对摄像头抓拍照片、录制短视频。本 Server 只读,不含任何写入/控制设备的工具;设备的 IP/token 只保存在本地配置文件里,运行时完全不走小米云。

部署后,支持 MCP 的大模型客户端可以直接问:"客厅插座现在开着吗""卧室湿度多少""工作室摄像头现在拍到了什么"。

功能

  • 列出已配置设备及在线状态

  • 读取设备全部实时属性 / 单个属性

  • 获取设备硬件信息(型号、固件、MAC)

  • 摄像头抓拍照片(返回 JPEG 图片)、录制 N 秒视频(保存为 MP4)

  • 支持 MIoT 协议(siid/piid)与传统 miIO 协议(get_prop)两类设备

  • 两种传输模式:stdio(本地)和 sse(远程 HTTP)

只读设计:本 Server 刻意不提供任何写入/控制工具(不能开关设备、不能改参数、无原始命令透传),避免大模型误操作家里的电器。

Related MCP server: Xiaomi smart home MCP server

前置条件:获取设备 IP 与 token

本地直连每个设备都需要 IP + 32 位 token + model。token 需一次性从小米云获取(之后运行时纯本地):

pip install python-miio
miiocli cloud   # 用小米账号登录,列出所有设备的 IP / token / model

将结果填入设备清单文件(见下)。建议在路由器为设备保留固定 IP,避免 DHCP 变化。

设备清单配置

复制示例并填入你的真实设备(参考 devices.example.json):

cp devices.example.json devices.json

格式为设备数组。普通 miIO/MIoT 设备:

[
  {
    "id": "living_room_plug",
    "name": "客厅插座",
    "ip": "192.168.31.100",
    "token": "0123456789abcdef0123456789abcdef",
    "model": "cuco.plug.v3",
    "protocol": "miot",
    "properties": {
      "switch_on":   { "siid": 2, "piid": 1, "desc": "开关" },
      "temperature": { "siid": 2, "piid": 6, "desc": "设备温度(°C)" }
    }
  }
]

  • protocol: miot(新设备,用 siid/piid)或 legacy(老设备,properties 为属性名数组)

  • MIoT 设备的 siid/piid 可在 spec.miot-spec.com 按型号查到

摄像头(protocol: "camera")不走 python-miio,而是从一条本地 RTSP 流抓帧/录制,只需填 rtsp_url:

{
  "id": "study_cam",
  "name": "工作室摄像头",
  "protocol": "camera",
  "rtsp_url": "rtsp://127.0.0.1:8554/camera_1"
}

⚠️ devices.json 含 token,已在 .gitignore 中排除,切勿提交到仓库。

摄像头的 RTSP 从哪来

米家摄像头不走 UDP:54321,本 Server 只负责用 ffmpeg 从一个现成的 RTSP 地址抓帧/录制。你需要另有一个把摄像头发布成本地 RTSP 的网关(例如把小米 P2P 流通过 MediaMTX 重发布为 rtsp://127.0.0.1:8554/camera_x),把该地址填进 rtsp_url 即可。运行本 Server 的机器需能访问该 RTSP,且已安装 ffmpeg。

快速开始

本地开发运行

pip install -e ".[sse]"

cp .env.example .env         # 按需修改
cp devices.example.json devices.json && vim devices.json
export MCP_XIAOMI_DEVICES=$PWD/devices.json

# stdio 模式(本地 MCP 客户端)
MCP_TRANSPORT=stdio python -m mcp_xiaomi_server.server

# SSE 模式(远程 MCP 客户端)
MCP_TRANSPORT=sse python -m mcp_xiaomi_server.server

摄像头抓拍/录制依赖 ffmpeg,请确保已安装(Docker 镜像已内置)。

Docker 部署

本地控制需容器与设备同一局域网,compose 使用 network_mode: host(仅 Linux 宿主机)。

cp devices.example.json devices.json && vim devices.json
docker compose up -d

CI/CD 自动构建发布

在仓库 Settings → Secrets and variables → Actions 添加:

Secret

说明

HARBOR_USERNAME

Harbor 用户名

HARBOR_PASSWORD

Harbor 密码或访问令牌

镜像仓库地址已固定为 harbor.zkjgy.online/library(写死在 workflow 中)。

打 tag 触发构建:

git tag v1.1.0
git push origin v1.1.0

自动构建 amd64(x86 runner)+ arm64(原生 ARM runner)多架构镜像,推送 Harbor 并创建 GitHub Release。

MCP 客户端配置

SSE(远程)

{
  "mcpServers": {
    "xiaomi": {
      "url": "http://<your-server-ip>:8092/sse"
    }
  }
}

stdio(本地)

{
  "mcpServers": {
    "xiaomi": {
      "command": "python",
      "args": ["-m", "mcp_xiaomi_server.server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MCP_XIAOMI_DEVICES": "/path/to/devices.json"
      }
    }
  }
}

环境变量

变量

默认值

说明

MCP_IMAGE

harbor.zkjgy.online/library/mcp-xiaomi-server:latest

Docker 镜像地址

MCP_TRANSPORT

sse

传输模式:stdio 或 sse

MCP_HOST

0.0.0.0

SSE 模式监听地址

MCP_PORT

8092

SSE 模式监听端口

MCP_XIAOMI_DEVICES

~/.config/mcp-xiaomi-server/devices.json

设备清单文件路径

MCP_XIAOMI_TIMEOUT

5

单次设备通信超时(秒)

MCP_XIAOMI_FFMPEG

ffmpeg

ffmpeg 可执行文件路径(摄像头抓拍/录制用)

MCP_XIAOMI_CLIP_DIR

系统临时目录

摄像头录制 MP4 的保存目录

MCP 工具列表

工具

说明

xiaomi_list_devices

列出设备(含摄像头)及在线状态

xiaomi_get_status

读取某设备全部实时属性(主力工具)

xiaomi_get_property

读取单个属性实时值

xiaomi_device_info

设备硬件信息与在线判断

xiaomi_camera_snapshot

抓取摄像头当前画面,返回 JPEG 图片

xiaomi_camera_clip

录制摄像头一段视频(默认 10 秒),返回 MP4 路径

xiaomi_get_server_status

服务器与配置状态

本 Server 为只读:不提供设置属性、开关设备或原始命令透传等写入工具。

工具调用示例

列出设备:  xiaomi_list_devices()
读实时状态:xiaomi_get_status(device_id="living_room_plug")
读单个属性:xiaomi_get_property(device_id="bedroom_humidifier", property="humidity")
摄像头抓拍:xiaomi_camera_snapshot(device_id="study_cam")
摄像头录制:xiaomi_camera_clip(device_id="study_cam", seconds=10)

项目结构

mcp-xiaomi-server/
├── src/mcp_xiaomi_server/
│   ├── server.py                # MCP 服务器入口,工具定义与分发
│   ├── camera.py                # 摄像头抓拍/录制(ffmpeg 拉本地 RTSP)
│   └── mihome/
│       ├── base.py              # 设备配置与数据模型
│       ├── local.py             # python-miio 本地只读封装
│       └── registry.py          # 设备清单加载与管理
├── devices.example.json         # 设备清单示例
├── Dockerfile
├── docker-compose.yaml
├── .github/workflows/
│   └── build-release.yaml       # CI/CD 工作流
├── requirements.txt
├── pyproject.toml
└── .env.example

局限与说明

  • 本 Server 只读,不含任何控制/写入设备的工具。

  • 普通设备仅覆盖 WiFi 直连设备。Zigbee/BLE 子设备(挂在小米网关下)需另走网关方案,不在本项目范围。

  • 普通设备的 MCP 服务器必须与设备处于同一局域网;token 变更(设备重置/重新配网)后需更新 devices.json。

  • 摄像头能力依赖一个外部的 RTSP 网关(把摄像头发布成本地 RTSP)与 ffmpeg;本 Server 本身不直接对接摄像头 SDK/云。

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ganyu123456/mcp-xiaomi-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server