Hermejia

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

hljs language-bash

# 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

hljs language-bash

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:

hljs language-bash

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:

hljs language-bash

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

hljs language-json

{
  "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:

hljs language-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

hljs language-bash

source venv/bin/activate
python test_mijia.py

For interactive testing:

hljs language-bash

python test_mijia.py -i

📁 Project Structure

hljs language-graphql

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

Hermejia

🌍 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

hljs language-bash

# 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

hljs language-bash

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:

hljs language-bash

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:

hljs language-bash

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

hljs language-json

{
  "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:

hljs language-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

hljs language-bash

source venv/bin/activate
python test_mijia.py

For interactive testing:

hljs language-bash

python test_mijia.py -i

📁 Project Structure

hljs language-graphql

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

Hermejia

Hermejia

✨ What is this?

🚀 Quick Start

📋 Requirements

🔧 Manual Installation

🔐 Authentication

🤖 Agent Configuration

Generic stdio MCP

Hermes Agent

Kimi CLI / Other stdio MCP clients

Claude Desktop / Cursor

🛠️ Available Tools

🧪 Testing

📁 Project Structure

⚠️ Troubleshooting

📄 License

🙏 Acknowledgments

Similar Packages

Hermejia

Hermejia

✨ What is this?

🚀 Quick Start

📋 Requirements

🔧 Manual Installation

🔐 Authentication

🤖 Agent Configuration

Generic stdio MCP

Hermes Agent

Kimi CLI / Other stdio MCP clients

Claude Desktop / Cursor

🛠️ Available Tools

🧪 Testing

📁 Project Structure

⚠️ Troubleshooting

📄 License

🙏 Acknowledgments

Similar Packages