Mijiaapi MCP

🚀 My MCP Server · Mi Home Smart Control

This is a Model Context Protocol (MCP) server built with TypeScript and Python. It integrates the smart home capabilities of Mi Home provided by mijiaAPI, supporting common operations such as QR code login, device listing, attribute reading and setting, scene linkage, consumable query, and statistical data retrieval.

✨ Features

Each tool supports use_mock=true, which is convenient for debugging without a real account.

🧱 Project Structure

my-mcp-server/
├── src/index.ts                  # MCP main entry (TypeScript)
├── dist/index.js                 # Build output
├── python_scripts/
│   ├── mijia_helper.py           # Login, cache, and API encapsulation
│   ├── mijia_tool.py             # Action routing script
│   ├── get_mijia_devices.py      # Compatible with the old entry (delegated to mijia_tool)
│   ├── get_device_status.py
│   ├── control_device.py
│   ├── requirements.txt          # Python dependencies
│   └── test_environment.py       # Environment detection script
├── README.md / SETUP_GUIDE.md    # Documentation
└── ...

🚀 Installation and Build

# Install Node dependencies
npm install

# Install Python dependencies (recommended to execute in a virtual environment)
pip install -r python_scripts/requirements.txt

# Build TypeScript
npm run build

🔐 First-time QR Code Login (Required)

1. Prepare the terminal: Ensure that the terminal can display ANSI characters correctly (to show the QR code).

2. Execute the login command (choose either one):

   # Method 1: Use the Python module
   python -m mijiaAPI -l
   
   # Method 2: Use the CLI command
   mijiaAPI -l
   

3. The terminal will print an ASCII QR code and output an accessible QR code link.

4. Scan the QR code with the Mi Home app and confirm the login.

5. The authentication information will be automatically saved to ~/.config/mijia-api/auth.json (can be modified via MIJIA_AUTH_PATH).

6. Subsequently, when calling MCP tools, the Token will be automatically reused unless it expires.

💡 Usage Tip:

If you want to save the authentication information in the project directory, you can set MIJIA_AUTH_PATH=./.mijia-api/auth.json in the .env file.

⚙️ MCP Configuration Example

c:/Users/chenz/AppData/Local/CodeBuddyExtension/Cache/CodeBuddyIDE/CodeBuddy/mcp/settings.json

{
  "mcpServers": {
    "mijia-mcp-server": {
      "command": "node",
      "args": ["c:/Users/chenz/CodeBuddy/20251216173558/dist/index.js"],
      "type": "stdio",
      "env": {
        "PYTHON_PATH": "c:/Users/chenz/CodeBuddy/20251216173558/.venv/Scripts/python.exe",
        "PYTHON_SCRIPT_DIR": "c:/Users/chenz/CodeBuddy/20251216173558/python_scripts",
        "MIJIA_AUTH_PATH": "c:/Users/chenz/.config/mijia-api/auth.json"
      }
    }
  }
}

🛠️ Tool Parameter Reference

get_mijia_devices

• home_id (string, optional): Specify the home ID
• include_shared (boolean, default false)
• use_mock (boolean, optional)

get_device_status

• device_id or device_name (at least one)
• properties (string[]): List of attributes to be read (e.g., on, brightness)
• include_metadata (boolean, default true)
• sleep_time (number): Reading interval (seconds)

control_device

• device_id or device_name
• operation: set_property / run_action
• prop_name + value: Used for set_property
• action_name + action_value: Used for run_action
• action_kwargs / params: Provide additional parameters for the action

list_mijia_scenes

• home_id (string, optional)

run_mijia_scene

• scene_id (string) — from list_mijia_scenes
• home_id (string)

get_mijia_statistics

• payload: Consistent with api.get_statistics, for example:

{
  "payload": {
    "did": "device_did",
    "key": "7.1",
    "data_type": "stat_month_v3",
    "limit": 6,
    "time_start": 1700000000,
    "time_end": 1702592000
  }
}

get_device_spec

• model (string): Such as yeelink.light.lamp4

The parameters of other tools can be viewed in the JSON Schema in src/index.ts.

🧩 Debugging and Mock Mode

• Set MIJIA_USE_MOCK=1 through the .env file or MCP configuration to return mock data without a real account/device.
• Run python python_scripts/test_environment.py "{}" to check the status of Python dependencies.

🧱 Extension Development

1. Add a new action in python_scripts/mijia_tool.py.
2. Register an MCP tool for this action in src/index.ts.
3. Run npm run build.

📝 License

This project is licensed under the GPL-3.0 open-source license.

⚠️ Important Note

GPL-3.0 is a "strongly infectious" Copyleft license.

• ✅ You can freely use, modify, and distribute this project.
• ✅ You can use it for commercial purposes.
• ⚠️ If you use, modify, or distribute this code in your project (including as a library dependency), your entire project must also be open-sourced under the GPL-3.0 or a compatible license.
• ⚠️ You must make the source code public and declare the modifications.

For more details, please refer to the LICENSE file.