Skip to main content
Glama
HuishanLi1997

Hermejia

by HuishanLi1997
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

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