# Hermejia

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io/)

🌍 [English](README.md) · [中文](README.zh.md) · [日本語](README.ja.md)

> **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](https://github.com/nickel110/mijiaAPI) library into a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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

```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

```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:

```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:

```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

```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`:

```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`](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

```bash
source venv/bin/activate
python test_mijia.py
```

For interactive testing:

```bash
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](LICENSE) — Copyright (c) 2026 scsagentclub.  
Core MCP server files are derived from [oujiafan/mcp-mijia](https://github.com/oujiafan/mcp-mijia), also under MIT.

## 🙏 Acknowledgments

- [mijiaAPI](https://github.com/nickel110/mijiaAPI) by nickel110
- [mcp-mijia](https://github.com/oujiafan/mcp-mijia) by oujiafan
- [Model Context Protocol](https://modelcontextprotocol.io/)