Hermejia

License: MIT Python 3.10+ MCP

🌍 English · 中文 · 日本語

Hermes + Mijia = Hermejia
A one-click MCP server that lets any AI agent control Xiaomi Mi Home (Mijia) smart devices through natural language.

✨ What is this?

Hermejia wraps the mijiaAPI library into a Model Context Protocol (MCP) server. After a one-time QR-code login, your AI agent can:

• List homes, rooms, devices, and scenes
• Read device properties (temperature, brightness, power, etc.)
• Set properties and run actions
• Turn devices on/off/toggle or run entire scenes

🚀 Quick Start

# 1. Clone
git clone https://github.com/HuishanLi1997/HuishanLi1997.git
cd Hermejia

# 2. One-click setup (creates venv, installs deps, runs QR auth)
bash scripts/setup.sh

# 3. Add the generated MCP config to your agent and restart it

After setup, open mcp_config.json (or the config printed by setup.sh) and add it to your agent.

📋 Requirements

• Linux / macOS / WSL (Windows is untested but may work)
• Python 3.10+
• Mi Home app on your phone for QR-code login

🔧 Manual Installation

git clone https://github.com/HuishanLi1997/HuishanLi1997.git
cd Hermejia
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

🔐 Authentication

Xiaomi requires QR-code login for new devices. Run the helper and scan the generated QR code with the Mi Home app:

source venv/bin/activate
python scripts/auth_login.py

The token is saved to ~/.config/mijia-api/auth.json by default. To use a custom path:

export MIJIA_AUTH_PATH=/path/to/your/auth.json
python scripts/auth_login.py

Tokens last about 30 days; re-run auth_login.py to refresh.

🤖 Agent Configuration

Generic stdio MCP

{
  "mcpServers": {
    "hermejia": {
      "type": "stdio",
      "command": "/full/path/to/Hermejia/venv/bin/python",
      "args": ["-m", "mijia"],
      "env": {
        "PYTHONPATH": "/full/path/to/Hermejia"
      }
    }
  }
}

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  hermejia:
    command: "/full/path/to/Hermejia/venv/bin/python"
    args: ["-m", "mijia"]
    workdir: "/full/path/to/Hermejia"
    env:
      PYTHONPATH: "/full/path/to/Hermejia"
    timeout: 30

Kimi CLI / Other stdio MCP clients

Use the mcp_config.json generated in the project root and point your client to it.

Claude Desktop / Cursor

Copy the mcpServers block from mcp_config.json into your client config and adjust paths.

See docs/CONFIG.md for detailed per-client examples.

🛠️ Available Tools

Tool	Description
list_homes	List all Mi Home homes
list_devices	List devices (optionally filtered by home)
list_device_capabilities	Show supported properties and actions
get_device_properties	Get all property values
get_device_property	Get a single property value
set_device_property	Set a property value
run_device_action	Run a device action
control_device	High-level control: on, off, toggle, property=value
list_scenes	List automations/scenes
run_scene	Run a scene by ID

🧪 Testing

source venv/bin/activate
python test_mijia.py

For interactive testing:

python test_mijia.py -i

📁 Project Structure

Hermejia/
├── mijia.py              # MCP server (core tools)
├── mcp_pipe.py           # WebSocket stdio bridge for Xiaozhi-like clients
├── test_mijia.py         # Test / interactive CLI
├── scripts/
│   ├── setup.sh          # One-click setup
│   ├── auth_login.py     # QR-code auth + long-poll login
│   ├── auto_qr.py        # Auto-refresh QR code while waiting
│   └── gen_qrcode.py     # Generate QR image only
├── docs/
│   └── CONFIG.md         # Per-agent configuration guide
├── requirements.txt
├── mcp_config.json
├── LICENSE
└── README.md

⚠️ Troubleshooting

Issue	Solution
QR code expires before scanning	Use scripts/auto_qr.py, which refreshes the QR code automatically
ModuleNotFoundError: mijiaAPI	Make sure the MCP command points to venv/bin/python, not system Python
Agent does not see tools	Restart the agent process; MCP tools are loaded at startup
Token expired	Re-run scripts/auth_login.py

📄 License

MIT — Copyright (c) 2026 scsagentclub.
Core MCP server files are derived from oujiafan/mcp-mijia, also under MIT.

🙏 Acknowledgments

• mijiaAPI by nickel110
• mcp-mijia by oujiafan
• Model Context Protocol