aqara/aqara-mcp-server

English | 中文 | Français | 한국어 | Español | 日本語 | Deutsch | Italiano
**Aqara MCP Server** is a remote MCP service provided by Aqara Agent. It lets MCP-enabled AI applications securely connect to Aqara smart home capabilities. When you need MCP integration, configure the remote MCP URL provided by Aqara Agent.
> [!TIP]
> **Recommended: Official Aqara Agent Skills**
>
> If your application supports Agent Skills (such as Codex App, Cursor, or OpenClaw), we recommend using the official **Aqara Agent Skills** first. You can query and control homes/spaces, devices, scenes, automations, energy consumption, and more in natural language—without configuring an MCP server.
>
> - GitHub: aqara/aqara-agent-skills
> - ClawHub: aqara/aqara-agent
Table of Contents
- Overview
- Features
- How It Works
- Quick Start
- Prerequisites
- Step 1: Account Authentication
- Step 2: Configure Remote MCP
- Step 3: Verification
- Configuration Notes
- MCP Tool Reference
- Core Tools Overview
- Home and Positions
- Device Query and Control
- Scenes
- Automations
- Energy Consumption
- Lighting Effects
- Firmware
- Parameter Conventions
- License
Overview
The recommended MCP integration today centers on Aqara Agent:
- **Remote MCP**: For applications that support Streamable HTTP via https://agent.aqara.com/open/mcp.
- **Aqara Agent Skills**: For applications with Agent Skills—install skills without manually configuring an MCP server.
- **MCP Tool capabilities**: Cover smart home operations across homes/spaces, devices, scenes, automations, energy consumption, lighting effects, and firmware.
Features
- 🔍 **Flexible device queries**: Query device basics, real-time status, and control logs by home/space, device type, or device ID.
- ✨ **Comprehensive device control**: Control power, brightness, color temperature, temperature, fan speed, mode, curtain percentage, and more on Aqara devices.
- 🎬 **Smart scene management**: Query and run scenes, and review scene execution history.
- ⏰ **Automation queries**: Query automation rules and their execution history.
- 📈 **Energy statistics**: Query electricity usage and cost by room/space or device, with aggregated and detailed views.
- 💡 **Lighting effect management**: Query lighting scenarios/effects, apply specified effects, and query effect configuration parameters.
- 🔄 **Firmware management**: Query current and available firmware versions, and start device firmware upgrades.
- 🏠 **Multiple homes and spaces**: List homes on your Aqara account and rooms/spaces in the current home.
- 🔌 **Remote MCP integration**: Connect via an MCP URL for apps such as Cursor and Codex App.
- 🔐 **Secure authentication**: Obtain aqara_api_key after signing in to Aqara Agent—keep credentials safe when configuring.
How It Works
In remote MCP mode, the application connects over HTTP to Aqara Agent’s MCP service and includes the bearer token generated on the login page. Aqara Agent validates credentials, executes tool calls, and returns results to the application:
1. **AI App / MCP host**: The user sends natural-language instructions from Cursor, Codex App, and similar apps.
2. **Aqara Agent**: Validates user credentials, interprets, and runs the corresponding Tools.
3. **Aqara Cloud API**: Performs data queries or control actions for devices, scenes, automations, energy consumption, lighting effects, firmware, and more.
---
Quick Start
Prerequisites
- An **Aqara account** with registered smart devices.
- An **application that supports remote MCP**, such as Cursor or Codex App.
- **Aqara Agent credentials**: aqara_api_key and aqara_mcp_url from the login page.
Step 1: Account Authentication
1. **Open the login page**:
https://agent.aqara.com/login
2. **Complete sign-in**:
- Sign in with your Aqara account.
- After sign-in, copy the aqara_api_key shown on the page.
- For MCP configuration, use the aqara_mcp_url on the page—typically https://agent.aqara.com/open/mcp.
3. **Store credentials securely**:
> Keep your aqara_api_key safe. Do not commit it to a repository, publish it in screenshots, or share it with others.
Step 2: Configure Remote MCP
Cursor
1. Open Cursor Settings, go to Tools & MCPs, and click New MCP Server.