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

Set OAuth token:
CODEBLOCK1

Get your token:

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

Quick Start

Query Devices and Scenes

CODEBLOCK2

Control Devices

CODEBLOCK3

Control Air Conditioner

CODEBLOCK4

Trigger Scenes

CODEBLOCK5

MCP Tools Reference

1. listhomedevicesandscenes

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 listhomedevicesandscenes
INLINECODE9 (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. controlairconditioner

Description: Control air conditioner temperature and mode.

Parameters:

- device_id (string, required): Air conditioner device ID (AIR_CONDITION category)
INLINECODE13 (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)
INLINECODE19 (string, optional): Temperature change amount, default "1" (for Increment/Decrement)
INLINECODE20 (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. smarthomeassistant

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

CODEBLOCK10

Example 2: Leaving Home

CODEBLOCK11

Example 3: Check All Devices

CODEBLOCK12

Device Categories

Category	Description	Control Methods
LIGHT	Smart lights	controldevice (on/off)
AIRCONDITION

Error Handling

CODEBLOCK13

Troubleshooting

Authentication Errors:

- Verify MXCHIP_OAUTH_TOKEN is set correctly
Token should start with INLINECODE29
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 INLINECODE32

Invalid Parameters:

- Temperature range: 16-32°C
Valid modes: COOL, HEAT, AUTO, FAN, DEHUMIDIFICATION, SLEEP
Scene ID format: INLINECODE33

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/

- mxchipmcpclient.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_<your_token>
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
Feature Requests: Submit via Smart Plus APP feedback
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

Mxchip 智能控制

通过 MXCHIP MCP 服务控制智家精灵 APP 中配置的智能家居设备。

开发者： 上海庆科信息技术有限公司
官方网站： https://www.mxchip.com/
GitHub： https://github.com/mxchip
支持： https://app.api.cloud.mxchip.com:2443/oauth2/mcp/oauth

概述

本技能为 AI 智能体提供对智家精灵 APP 中配置的智能家居设备的完整控制能力，基于 MCP（模型上下文协议）实现。支持设备管理、空调控制和场景自动化，通过 HTTP 协议使用 JSON-RPC 2.0 通信。

协议： MCP + JSON-RPC 2.0
传输方式： HTTP
目标应用： 智家精灵 APP

关于 MXCHIP

上海庆科信息技术有限公司是中国领先的物联网解决方案提供商，专注于：

- 智能家居设备连接
物联网云平台服务
AI 驱动的家居自动化
MCP（模型上下文协议）集成

智家精灵是 MXCHIP 官方智能家居应用，支持用户：

- 配置和管理智能设备
创建自动化场景
远程控制设备
与 AI 助手集成

环境配置

安装依赖：
bash
pip install requests

设置 OAuth 令牌：
bash
export MXCHIPOAUTHTOKEN=oauth2YOURTOKEN_HERE

获取令牌：

1. 访问：https://app.api.cloud.mxchip.com:2443/oauth2/mcp/oauth
输入您的智家精灵 APP 账户凭证
复制 OAuth2 访问令牌

快速开始

查询设备和场景

python from mxchipmcpclient import MxchipMCPClient

client = MxchipMCPClient()

列出所有设备和场景

result = client.listhomedevicesandscenes()

访问设备

for device in result.get(devices, []): print(f{device[name]}: {device[category]})

访问场景

for scene in result.get(scenes, []): print(f{scene[name]}: {scene[scene_id]})

控制设备

python

打开灯

client.controldevice(device001, TurnOnRequest)

关闭开关

client.controldevice(device002, TurnOffRequest)

控制空调

python

设置温度为 26°C

client.controlairconditioner( acdeviceid, SetTemperatureRequest, temperature=26 )

温度升高 2°C

client.controlairconditioner( acdeviceid, IncrementTemperatureRequest, delta=2 )

设置制冷模式

client.controlairconditioner( acdeviceid, SetModeRequest, mode=COOL )

触发场景

python

触发回家场景

client.triggerscene(sceneidcoming_home)

MCP 工具参考

1. listhomedevicesandscenes

描述： 获取家中所有智能设备和场景。

参数： 无

返回：

- devices：设备对象数组

- device_id：设备唯一标识符
- name：设备名称
- category：设备类型（LIGHT、AIR_CONDITION、SWITCH 等）
- status：当前设备状态

- scenes：场景对象数组

- sceneid：场景标识符（格式：sceneidxxx）
- name：场景名称（例如回家、睡眠模式）

示例：
python
result = client.listhomedevicesandscenes()
devices = result.get(devices, [])
scenes = result.get(scenes, [])

2. control_device

描述： 控制设备电源状态（开/关）。

参数：

- deviceid（字符串，必填）：来自 listhomedevicesand_scenes 的设备标识符
action（字符串，必填）：控制动作

- TurnOnRequest：打开设备
- TurnOffRequest：关闭设备

示例：
python

打开设备

client.controldevice(light001, TurnOnRequest)

关闭设备

client.controldevice(light001, TurnOffRequest)

3. controlairconditioner

描述： 控制空调温度和模式。

参数：

- deviceid（字符串，必填）：空调设备 ID（AIRCONDITION 类别）
action（字符串，必填）：控制动作类型

- IncrementTemperatureRequest：升高温度
- DecrementTemperatureRequest：降低温度
- SetTemperatureRequest：设置目标温度
- SetModeRequest：设置工作模式

- temperature（整数，可选）：目标温度 16-32°C（用于 SetTemperatureRequest）
delta（字符串，可选）：温度变化量，默认1（用于 Increment/Decrement）
mode（字符串，可选）：工作模式（用于 SetModeRequest）

- COOL：制冷模式
- HEAT：制热模式
- AUTO：自动模式
- FAN：仅送风
- DEHUMIDIFICATION：除湿
- SLEEP：睡眠模式

示例：
python

设置温度为 26°C

client.controlairconditioner(ac_001, SetTemperatureRequest, temperature=26)

温度升高 2°C

client.controlairconditioner(ac_001, IncrementTemperatureRequest, delta=2)

设置制冷模式

client.controlairconditioner(ac_001, SetModeRequest, mode=COOL)

设置制热模式

client.controlairconditioner(ac_001, SetModeRequest, mode=HEAT)

4. trigger_scene

描述： 触发智能家居场景，一次控制多个设备。

参数：

- sceneid（字符串，必填）：场景标识符（格式：sceneidxxx）

常见场景：

- 回家模式
离家模式
睡眠模式
观影模式

示例：
python
client.triggerscene(sceneidcoming_home)

MCP 提示参考

MCP 服务提供三个专用提示：

1. device_control

用途： 设备控制助手，专注于控制灯光、开关、窗帘等。

使用时机： 当用户想要控制特定设备类型时（打开/关闭灯光、开关）

2. scene_trigger

用途： 场景控制助手，用于管理预设的自动化场景

使用时机： 当用户想要执行回家、睡眠模式等场景时

3. smarthomeassistant

用途： 全功能智能家居助手

使用时机： 当用户需要全面的家居自动化时（查询 + 控制 + 场景）

常见用例

示例 1：早晨例行

python client = MxchipMCPClient()

打开卧室灯

client.controldevice(bedroomlight, TurnOnRequest)

设置空调到舒适温度

client.controlairconditioner(bedroom_ac, SetTemperatureRequest, temperature=24)

打开窗帘（如果支持）

client.controldevice(curtain001, TurnOnRequest)

示例 2：离家

python

触发离家场景

client.triggerscene(sceneidleaving_home)

或手动关闭设备

client.controldevice(livingroom_light, TurnOffRequest) client.controldevice(bedroomac, TurnOffRequest)

示例 3：检查所有设备

python result = client.listhomedevicesandscenes()

for device in result.get(devices, []):
status = device.get(status, 未知)
print(f{device[name]}: {status})

设备类别

类别	描述	控制方法
LIGHT	智能灯	controldevice（开/关）
AIRCONDITION

mxchip-smart-control智能家居控制