miwifi-mcp

小米 / 红米路由器 MCP Server —— 让 AI 助手（Claude Desktop、Reasonix、Cursor 等支持 MCP 的客户端）直接管理你的小米路由器。

Xiaomi / Redmi router MCP server — manage your router from any MCP-capable AI assistant.

✨ 功能

读（只读查询）

写（会改变路由器状态）

逃生口

❌ 故意不提供

• shutdown —— 远程执行后必须物理拔插电源才能重启，断网自毁

• reset —— 恢复出厂设置

• 修改管理密码

Related MCP server: AsusWRT MCP Server

📦 安装

git clone https://github.com/2670321532/miwifi-mcp.git
cd miwifi-mcp
pip install -r requirements.txt

国内建议加 pip 镜像：-i https://pypi.tuna.tsinghua.edu.cn/simple

⚙️ 配置

复制模板并填入你的信息：

cp config.example.json config.local.json

{
  "host": "192.168.31.1",
  "user": "admin",
  "password": "你的路由器后台管理密码"
}

优先级：环境变量 > config.local.json > 内置默认值

config.local.json 不要提交到 Git（已在 .gitignore 中）。

🔌 接入 MCP 客户端

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "miwifi": {
      "command": "python",
      "args": ["/absolute/path/to/miwifi-mcp/server.py"]
    }
  }
}

Reasonix（config.toml）：

[[plugins]]
  name = "miwifi"
  command = "python"
  args = ["/absolute/path/to/miwifi-mcp/server.py"]

重启客户端即可看到 miwifi_* 工具。

🔑 登录算法（重点）

小米路由器的登录是 challenge-response，而且新旧固件算法不同。 本项目的实现基于对路由器管理页面 JS 的逆向，已适配两种模式：

// 路由器页面里决定用哪种算法的变量
var newEncryptMode = parseInt('1')   // 1 → SHA256，0 → SHA1

nonce = [0, deviceId, 时间戳, 随机数].join('_')   // deviceId = 路由器 MAC（带冒号）

// newEncryptMode == 1
password = SHA256( nonce + SHA256(明文密码 + key) )
// newEncryptMode == 0
password = SHA1( nonce + SHA1(明文密码 + key) )

其中 key 从管理页面抓取（每个固件可能不同），然后：

POST /cgi-bin/luci/api/xqsystem/login
Content-Type: application/x-www-form-urlencoded      ← ⚠️ 必须是 form-data，不能用 JSON
body: username=admin&password=<hash>&logtype=2&nonce=<nonce>

成功返回 {"code":0,"token":"<stok>"}，之后所有请求带上：

GET /cgi-bin/luci/;stok=<token>/<api路径>

⚠️ 错误响应速判

登录速率限制：连续 4 次失败会被临时锁定，请勿盲目重试。

📌 端点差异

部分固件改了 API 路径，本项目已做兼容：

🧪 实测环境

理论兼容：所有使用 LuCI HTTP API 的小米 / 红米路由器（本项目会自动识别 newEncryptMode）。 如果你的型号不行，欢迎提 issue 附上固件版本和错误响应。

🔒 安全说明

1. 密码只存本地 —— config.local.json（已 gitignore）或环境变量；代码里不含任何凭据

2. 只读优先 —— miwifi_luci_get 有黑名单，无法通过它触发修改操作

3. 不提供危险操作 —— shutdown / reset / 改密码被刻意排除

4. PPPoE 密码脱敏 —— 路由器原始返回的宽带账号密码会被替换为 <已脱敏>

5. 建议 —— 路由器后台密码不要与其他服务共用

🛠️ 排错

login key not found on web page → 路由器管理页面结构不同。手动访问 http://<路由器IP>/cgi-bin/luci/web， 查看源码里是否有 key: '...' 和 deviceId = '...'。

login failed: {'code': 401, 'msg': 'not auth'} → 密码错，或固件的加密模式判断有误。确认 newEncryptMode 的值。

login failed: {'code': 401, 'msg': 'Invalid token'} → 请求不是 form-data。检查 Content-Type。

工具返回 404 / bad JSON → 该固件的端点路径不同，用 miwifi_luci_get 试探正确路径。

📄 License

MIT

🙏 致谢

• python-xiaomi-miwifi —— 提供了 LuCI API 的封装与端点映射

• Model Context Protocol —— MCP 协议与 SDK

本项目与小米公司无关联，为第三方非官方工具。使用风险自负。