mxchip-smart-control

---

name: mxchip-smart-control description: "Control smart home devices configured in Smart Plus APP. Use when you need to: (1) Query devices and scenes (lights, AC, switches), (2) Control device power (turn on/off), (3) Control air conditioner (temperature, mode), (4) Trigger smart scenes. Requires MXCHIP_OAUTH_TOKEN environment variable."

---

Mxchip Smart Control

Control smart home devices configured in Smart Plus APP (智家精灵) through MXCHIP MCP service.

Developer: Shanghai MXCHIP Information Technology Co., Ltd. (上海庆科信息技术有限公司) Official Website: https://www.mxchip.com/ GitHub: https://github.com/mxchip Support: https://app.api.cloud.mxchip.com:2443/oauth2/mcp/oauth

Overview

This skill provides AI agents with complete control over smart home devices configured in Smart Plus (智家精灵) APP using the MCP (Model Context Protocol). Supports device management, air conditioner control, and scene automation through JSON-RPC 2.0 over HTTP.

Protocol: MCP with JSON-RPC 2.0 Transport: HTTP Target Application: Smart Plus APP (智家精灵)

About MXCHIP

Shanghai MXCHIP Information Technology Co., Ltd. (上海庆科信息技术有限公司) is a leading IoT solution provider in China, specializing in:

Smart home device connectivity

IoT cloud platform services

AI-powered home automation

MCP (Model Context Protocol) integration

Smart Plus (智家精灵) is MXCHIP's official smart home application that allows users to:

Configure and manage smart devices

Create automation scenes

Control devices remotely

Integrate with AI assistants

Environment Setup

Install dependencies:

pip install requests

Set OAuth token:

export MXCHIP_OAUTH_TOKEN="oauth2_YOUR_TOKEN_HERE"

Get your token: 1. Visit: https://app.api.cloud.mxchip.com:2443/oauth2/mcp/oauth 2. Enter your Smart Plus APP account credentials 3. Copy the OAuth2 access token

Quick Start

Query Devices and Scenes

from mxchip_mcp_client import MxchipMCPClient
client = MxchipMCPClient()
List all devices and scenes
result = client.list_home_devices_and_scenes()
Access devices
for device in result.get('devices', []):
    print(f"{device['name']}: {device['category']}")
Access scenes
for scene in result.get('scenes', []):
    print(f"{scene['name']}: {scene['scene_id']}")

Control Devices

# Turn on light
client.control_device("device_001", "TurnOnRequest")
Turn off switch
client.control_device("device_002", "TurnOffRequest")

Control Air Conditioner

# Set temperature to 26°C
client.control_air_conditioner(
    "ac_device_id",
    "SetTemperatureRequest",
    temperature=26
)
Increase temperature by 2°C
client.control_air_conditioner(
    "ac_device_id",
    "IncrementTemperatureRequest",
    delta="2"
)
Set cooling mode
client.control_air_conditioner(
    "ac_device_id",
    "SetModeRequest",
    mode="COOL"
)

Trigger Scenes

# Trigger "Coming Home" scene
client.trigger_scene("sceneid_coming_home")

MCP Tools Reference

1. list_home_devices_and_scenes

Description: Get all smart devices and scenes in your home.

Parameters: None

Returns:

devices: Array of device objects

- device_id: Device unique identifier - name: Device name - category: Device type (LIGHT, AIR_CONDITION, SWITCH, etc.) - status: Current device status

scenes: Array of scene objects

- scene_id: Scene identifier (format: sceneid_xxx) - name: Scene name (e.g., "Coming Home", "Sleep Mode")

Example:

result = client.list_home_devices_and_scenes()
devices = result.get('devices', [])
scenes = result.get('scenes', [])

---

2. control_device

Description: Control device power state (on/off).

Parameters:

device_id (string, required): Device identifier from list_home_devices_and_scenes

action (string, required): Control action

- "TurnOnRequest": Turn on device - "TurnOffRequest": Turn off device

Example:

# Turn on device
client.control_device("light_001", "TurnOnRequest")
Turn off device
client.control_device("light_001", "TurnOffRequest")

---

3. control_air_conditioner

Description: Control air conditioner temperature and mode.

Parameters:

device_id (string, required): Air conditioner device ID (AIR_CONDITION category)

action (string, required): Control action type

- "IncrementTemperatureRequest": Increase temperature - "DecrementTemperatureRequest": Decrease temperature - "SetTemperatureRequest": Set target temperature - "SetModeRequest": Set working mode

temperature (int, optional): Target temperature 16-32°C (for SetTemperatureRequest)

delta (string, optional): Temperature change amount, default "1" (for Increment/Decrement)

mode (string, optional): Working mode (for SetModeRequest)

- "COOL": Cooling mode - "HEAT": Heating mode - "AUTO": Auto mode - "FAN": Fan only - "DEHUMIDIFICATION": Dehumidify - "SLEEP": Sleep mode

Examples:

# Set temperature to 26°C
client.control_air_conditioner("ac_001", "SetTemperatureRequest", temperature=26)
Increase temperature by 2°C
client.control_air_conditioner("ac_001", "IncrementTemperatureRequest", delta="2")
Set cooling mode
client.control_air_conditioner("ac_001", "SetModeRequest", mode="COOL")
Set heating mode
client.control_air_conditioner("ac_001", "SetModeRequest", mode="HEAT")

---

4. trigger_scene

Description: Trigger a smart home scene to control multiple devices at once.

Parameters:

scene_id (string, required): Scene identifier (format: sceneid_xxx)

Common Scenes:

Coming Home Mode (回家模式)

Leaving Home Mode (离家模式)

Sleep Mode (睡眠模式)

Movie Mode (观影模式)

Example:

client.trigger_scene("sceneid_coming_home")

---

MCP Prompts Reference

The MCP service provides three specialized prompts:

1. device_control

Purpose: Device control assistant focused on controlling lights, switches, curtains, etc.

When to use: When user wants to control specific device types (turn on/off lights, switches)

2. scene_trigger

Purpose: Scene control assistant for managing preset automation scenes

When to use: When user wants to execute scenes like "Coming Home", "Sleep Mode"

3. smart_home_assistant

Purpose: Full-featured smart home assistant

When to use: When user needs comprehensive home automation (query + control + scenes)

Common Use Cases

Example 1: Morning Routine

client = MxchipMCPClient()
Turn on bedroom light
client.control_device("bedroom_light", "TurnOnRequest")
Set AC to comfortable temperature
client.control_air_conditioner("bedroom_ac", "SetTemperatureRequest", temperature=24)
Open curtains (if supported)
client.control_device("curtain_001", "TurnOnRequest")

Example 2: Leaving Home

# Trigger "Leaving Home" scene
client.trigger_scene("sceneid_leaving_home")
Or manually turn off devices
client.control_device("living_room_light", "TurnOffRequest")
client.control_device("bedroom_ac", "TurnOffRequest")

Example 3: Check All Devices

result = client.list_home_devices_and_scenes()
for device in result.get('devices', []):
    status = device.get('status', 'Unknown')
    print(f"{device['name']}: {status}")

Device Categories

| Category | Description | Control Methods | |----------|-------------|-----------------| | LIGHT | Smart lights | control_device (on/off) | | AIR_CONDITION | Air conditioners | control_air_conditioner | | SWITCH | Smart switches | control_device (on/off) | | CURTAIN | Smart curtains | control_device (on/off) | | SOCKET | Smart sockets | control_device (on/off) |

Error Handling

from mxchip_mcp_client import (
    MxchipMCPClient,
    AuthenticationError,
    InvalidParameterError,
    MxchipMCPError
)
try:
    client = MxchipMCPClient()
    client.control_device("device_001", "TurnOnRequest")
except AuthenticationError as e:
    print(f"Auth failed: {e}")
    # Regenerate token
except InvalidParameterError as e:
    print(f"Invalid parameter: {e}")
    # Check parameters
except MxchipMCPError as e:
    print(f"MCP error: {e}")
    # Handle other errors

Troubleshooting

Authentication Errors:

Verify MXCHIP_OAUTH_TOKEN is set correctly

Token should start with oauth2_

Regenerate token at OAuth page if expired

Device Not Found:

Always call list_home_devices_and_scenes() first

Use exact device_id from the response

For AC control, ensure device category is AIR_CONDITION

Invalid Parameters:

Temperature range: 16-32°C

Valid modes: COOL, HEAT, AUTO, FAN, DEHUMIDIFICATION, SLEEP

Scene ID format: sceneid_xxx

Security Notes

OAuth token provides access to your smart home devices

Keep token secure and never commit to version control

Token has expiration time - regenerate when needed

Use environment variables for token storage

Resources

scripts/

mxchip_mcp_client.py - Official MCP client SDK

- Implements JSON-RPC 2.0 protocol - All 4 MCP tools wrapped as Python methods - Complete error handling - Type hints and documentation

references/

api_reference.md - Detailed API documentation

- JSON-RPC 2.0 protocol details - Complete parameter specifications - Error codes and handling - Advanced usage examples

---

README

Project Information

Skill Name: Mxchip Smart Control Developer: Shanghai MXCHIP Information Technology Co., Ltd. (上海庆科信息技术有限公司) Version: 1.0.2 License: MIT-0 (Free to use, modify, and redistribute) Protocol: MCP (Model Context Protocol) + JSON-RPC 2.0

About MXCHIP

Shanghai MXCHIP Information Technology Co., Ltd. (上海庆科信息技术有限公司) is a leading Chinese IoT solution provider founded in 2005. The company specializes in:

IoT Hardware: Wi-Fi modules, Bluetooth modules, IoT development boards

Cloud Services: MXCHIP Cloud platform for device management

Smart Home: Smart Plus APP for home automation

AI Integration: MCP protocol support for AI assistants

Smart Plus APP

Smart Plus (智家精灵) is MXCHIP's official smart home application that provides:

Device Management: Add and configure smart devices

Scene Automation: Create custom automation rules

Remote Control: Control devices from anywhere

Voice Control: Integration with AI assistants via MCP

Download:

iOS: App Store search "Smart Plus" or "智家精灵"

Android: Major app stores search "Smart Plus" or "智家精灵"

Supported Devices

This skill supports all devices configured in Smart Plus APP, including:

Switches: Smart plugs, power strips

Lights: Smart bulbs, LED strips, ceiling lights

Air Conditioners: Split ACs, central ACs

Sensors: Temperature, humidity, motion (via scenes)

Curtains: Smart curtain controllers

Other: Any device added to Smart Plus APP

API Access

MCP Endpoint: https://app.api.cloud.mxchip.com:2443/mcp OAuth Token: https://app.api.cloud.mxchip.com:2443/oauth2/mcp/oauth

Authentication: OAuth2 Bearer Token Format: oauth2_ Validity: Token expires after certain period (regenerate as needed)

Use Cases

#### For Home Users

Control devices with natural language

Trigger scenes with voice commands

Monitor device status

Automate daily routines

#### For Developers

Build AI-powered smart home applications

Integrate with OpenClaw ecosystem

Create custom automation workflows

Develop voice-controlled interfaces

Technical Stack

Client SDK: Python 3.7+ Dependencies: requests>=2.28.0 Protocol: MCP with JSON-RPC 2.0 over HTTP Authentication: OAuth2 Bearer Token

Support & Resources

Official Website: https://www.mxchip.com/ Documentation: See references/api_reference.md in this skill OAuth Token: https://app.api.cloud.mxchip.com:2443/oauth2/mcp/oauth GitHub: https://github.com/mxchip

Contributing

This skill is developed and maintained by Shanghai MXCHIP Information Technology Co., Ltd. For issues, feature requests, or contributions:

1. Issues: Contact MXCHIP support team 2. Feature Requests: Submit via Smart Plus APP feedback 3. Documentation: See skill documentation in scripts/ and references/ directories

Disclaimer

This skill is provided as-is for controlling devices configured in Smart Plus APP. Users must:

Have a valid Smart Plus APP account

Configure devices in the app before using this skill

Configure devices in the app before using this skill

Keep OAuth token secure and confidential

Comply with MXCHIP's terms of service

Changelog

v1.0.2 (2026-03-23)

Fixed JSON parsing for MCP response structure

Updated environment variable from ZHIJIA to MXCHIP

Added comprehensive documentation

Added Shanghai MXCHIP company information

v1.0.1 (2026-03-23)

Initial release

Support for 4 MCP tools

Support for 3 MCP prompts

---

© 2026 Shanghai MXCHIP Information Technology Co., Ltd. All rights reserved.

Query Devices and Scenes

from mxchip_mcp_client import MxchipMCPClient
client = MxchipMCPClient()
List all devices and scenes
result = client.list_home_devices_and_scenes()
Access devices
for device in result.get('devices', []):
    print(f"{device['name']}: {device['category']}")
Access scenes
for scene in result.get('scenes', []):
    print(f"{scene['name']}: {scene['scene_id']}")

Control Devices

# Turn on light
client.control_device("device_001", "TurnOnRequest")
Turn off switch
client.control_device("device_002", "TurnOffRequest")

Control Air Conditioner

# Set temperature to 26°C
client.control_air_conditioner(
    "ac_device_id",
    "SetTemperatureRequest",
    temperature=26
)
Increase temperature by 2°C
client.control_air_conditioner(
    "ac_device_id",
    "IncrementTemperatureRequest",
    delta="2"
)
Set cooling mode
client.control_air_conditioner(
    "ac_device_id",
    "SetModeRequest",
    mode="COOL"
)

Trigger Scenes

# Trigger "Coming Home" scene
client.trigger_scene("sceneid_coming_home")

Authentication Errors:

Verify MXCHIP_OAUTH_TOKEN is set correctly

Token should start with oauth2_

Regenerate token at OAuth page if expired

Device Not Found:

Always call list_home_devices_and_scenes() first

Use exact device_id from the response

For AC control, ensure device category is AIR_CONDITION

Invalid Parameters:

Temperature range: 16-32°C

Valid modes: COOL, HEAT, AUTO, FAN, DEHUMIDIFICATION, SLEEP

Scene ID format: sceneid_xxx