Aqara MCP Server

What is Aqara MCP Server about?

Enables AI assistants such as Claude, Cursor, or any MCP‑compatible client to interact with Aqara smart home devices through natural language. The server receives MCP tool calls, translates them into Aqara Cloud API requests, and returns results back to the client.

How to use Aqara MCP Server?

Prerequisites: Go 1.24+ (only if building from source), Git, an Aqara account with registered devices, and an MCP‑compatible client.

Installation

Binary (recommended): Download the latest executable from the GitHub Releases page and extract it.

Build from source:

git clone https://github.com/aqara/aqara-mcp-server.git
cd aqara-mcp-server
go mod tidy
go build -o aqara-mcp-server

Account Authentication: Open https://cdn.aqara.com/app/mcpserver/login.html, log in, and copy the generated token and region.

Client Configuration (example for Claude for Desktop):

{
  "mcpServers": {
    "aqara": {
      "command": "/path/to/aqara-mcp-server",
      "args": ["run", "stdio"],
      "env": {
        "token": "your_token_here",
        "region": "your_region_here"
      }
    }
  }
}

Adjust the path and environment values, then restart the client.

Start the Service: Run the binary with the run stdio (or future run http) mode. The client will now be able to call tools such as device_control, device_query, run_scenes, etc.

Key Features

Comprehensive device control (power, brightness, color temperature, mode, …)
Flexible queries for device lists, real‑time status, and historical logs
Smart scene management (list & execute)
Multi‑home support with home switching
Automation configuration (scheduled or delayed tasks via crontab syntax)
Secure token‑based authentication and signature verification
Cross‑platform Go binaries for Windows, macOS, and Linux
Modular tool architecture for easy extension

Use Cases

Voice or chat‑based control of lights, thermostats, curtains, etc.
Homeowners querying the current status of all devices in a specific room.
Executing a “Good Night” scene through a simple natural‑language command.
Setting up a nightly thermostat schedule without writing code.
Integrating Aqara devices into custom AI assistants or workflow bots.

FAQ

Q: Which AI assistants can I use? A: Any client that implements the MCP protocol, e.g., Claude for Desktop, Cursor, or custom MCP‑compatible tools.

Q: Do I need to run the server continuously? A: Yes, the server must be running while the client interacts with it. It can run as a background process or service.

Q: How is my token protected? A: The token is passed as an environment variable and never stored in source code. Keep it secret and rotate if compromised.

Q: Can I use HTTP instead of stdio? A: HTTP mode is planned for a future release. Currently, run stdio is the supported transport.

Q: Is there support for non‑Chinese regions? A: Supported regions include CN, US, EU, KR, SG, and RU – set the appropriate region env variable.

Aqara MCP Server is an intelligent home automation control service built on the MCP (Model Context Protocol). It enables any MCP-compatible AI assistant or API (such as Claude, Cursor, etc.) to interact with your Aqara smart home devices, providing natural language device control, status queries, and scene execution capabilities.

Table of Contents
Features
How It Works
Quick Start
API Tools Reference
Project Structure
- Directory Structure
- Core Files
Development Guide
License

Features

✨ Comprehensive Device Control: Support for precise control of various Aqara smart device attributes including power, brightness, color temperature, and operating modes
🔍 Flexible Device Queries: Query device lists and detailed status by room or device type
🎬 Smart Scene Management: Query and execute user-configured smart home scenes
📈 Device History: Query device historical state changes within specified time ranges
⏰ Automation Configuration: Configure scheduled or delayed device control tasks
🏠 Multi-Home Support: Query and switch between different homes under your account
🔌 MCP Protocol Compatibility: Full compliance with MCP protocol specifications for seamless AI assistant integration
🔐 Secure Authentication: Login-based authorization with signature-based security to protect user data and devices
🌐 Cross-Platform: Built with Go for compilation to multiple platform executables
🔧 Extensible: Modular design for easy addition of new tools and functionality

How It Works

Aqara MCP Server serves as a bridge between AI assistants and the Aqara smart home platform:

graph LR A[AI Assistant] --> B[MCP Client] B --> C[Aqara MCP Server] C --> D[Aqara Cloud API] D --> E[Smart Devices]

AI Assistant: Users issue commands through AI assistants (e.g., "Turn on the living room lights")
MCP Client: Parses user commands and calls appropriate Aqara MCP Server tools (e.g., device_control) per MCP protocol
Aqara MCP Server (This Project): Receives client requests, communicates with Aqara Cloud API using configured credentials to execute device operations or data queries
Response Flow: Aqara Cloud API returns results through Aqara MCP Server back to the MCP client, ultimately presented to the user

Quick Start

Prerequisites

Go (version 1.24 or higher) - Only required for building from source
Git (for building from source) - Optional
Aqara Account with registered smart devices
MCP-compatible client (such as Claude for Desktop, Cursor, etc.)

Installation

You can either download pre-built executables or build from source.

Option 1: Download Pre-built Binaries (Recommended)

Visit the GitHub Releases page to download the latest executable for your operating system:

📥 Go to Releases Page

Simply download and extract the appropriate package for your platform.

Option 2: Build from Source

# Clone the repository
git clone https://github.com/aqara/aqara-mcp-server.git
cd aqara-mcp-server

# Download dependencies
go mod tidy

# Build executable
go build -o aqara-mcp-server

After building, you'll have an aqara-mcp-server executable in the current directory.

Aqara Account Authentication

To enable MCP Server access to your Aqara account and device control, you must first complete login authorization.

Please visit the following URL to complete login authorization: 🔗 https://cdn.aqara.com/app/mcpserver/login.html

After successful login, you'll receive necessary authentication information (such as token, region) for use in subsequent configuration steps.

⚠️ Security Notice: Please keep your token information secure and do not share with others.

Client Configuration

Configuration methods vary slightly between different MCP clients. Here's an example of how to configure Claude for Desktop to use this MCP Server:

Claude for Desktop Configuration Example

Open Claude for Desktop Settings
Switch to the Developer tab, then click Edit Config to open the configuration file in a text editor

Add the configuration information from the "Login Success Page" to your client's configuration file claude_desktop_config.json

{
  "mcpServers": {
    "aqara": {
      "command": "/path/to/aqara-mcp-server",
      "args": ["run", "stdio"],
      "env": {
        "token": "your_token_here",
        "region": "your_region_here"
      }
    }
  }
}

Configuration Example

Configuration Parameters

command: Full path to your downloaded or built aqara-mcp-server executable
args: Use ["run", "stdio"] to start stdio transport mode
env: Environment variable configuration
- token: Access token obtained from Aqara login page
- region: Your Aqara account region (supported regions: CN, US, EU, KR, SG, RU)

Other MCP Clients

For other MCP protocol-compatible clients (such as ChatGPT, Cursor, etc.), configuration is similar:

Ensure the client supports MCP protocol
Configure executable path and startup parameters
Set environment variables token and region
Select appropriate transport protocol (recommend stdio)

Starting the Service

Standard Mode (Recommended)

Restart Claude for Desktop. You can then perform device control, device queries, scene execution, and other operations through natural language.

Example conversations:

"Turn on the living room lights"
"Set the bedroom air conditioner to cooling mode at 24 degrees"
"Show me all devices in every room"
"Run the goodnight scene"

Claude Chat Example

HTTP Mode (Coming Soon)

API Tools Reference

MCP clients can interact with Aqara smart home devices by calling these tools.

Device Control

device_control

Control smart home device states or attributes (such as power, temperature, brightness, color, color temperature, etc.).

Parameters:

endpoint_ids (Array<Integer>, Required): List of device IDs to control
control_params (Object, Required): Control parameter object containing specific operations:
- action (String, Required): Operation to execute (e.g., "on", "off", "set", "up", "down", "cooler", "warmer")
- attribute (String, Required): Device attribute to control (e.g., "on_off", "brightness", "color_temperature", "ac_mode")
- value (String | Number, Optional): Target value (required when action is "set")
- unit (String, Optional): Unit of the value (e.g., "%", "K", "℃")

Returns: Device control operation result message

Device Query

device_query

Get device list based on specified location (room) and device type (excludes real-time status information).

Parameters:

positions (Array<String>, Optional): List of room names. Empty array queries all rooms
device_types (Array<String>, Optional): List of device types (e.g., "Light", "WindowCovering", "AirConditioner", "Button"). Empty array queries all types

Returns: Markdown formatted device list including device names and IDs

device_status_query

Get current device status information (for querying real-time status like color, brightness, power state, etc.).

Parameters:

positions (Array<String>, Optional): List of room names. Empty array queries all rooms
device_types (Array<String>, Optional): List of device types. Same options as device_query. Empty array queries all types

Returns: Markdown formatted device status information

device_log_query

Query device historical log information.

Parameters:

endpoint_ids (Array<Integer>, Required): List of device IDs to query history for
start_datetime (String, Optional): Query start time in format YYYY-MM-DD HH:MM:SS (e.g., "2023-05-16 12:00:00")
end_datetime (String, Optional): Query end time in format YYYY-MM-DD HH:MM:SS
attributes (Array<String>, Optional): List of device attribute names to query (e.g., ["on_off", "brightness"]). Queries all recorded attributes if not provided

Returns: Markdown formatted device historical status information

Scene Management

get_scenes

Query all scenes under user's home, or scenes within specified rooms.

Parameters:

positions (Array<String>, Optional): List of room names. Empty array queries entire home's scenes

Returns: Markdown formatted scene information

run_scenes

Execute specified scenes by scene ID.

Parameters:

scenes (Array<Integer>, Required): List of scene IDs to execute

Returns: Scene execution result message

Home Management

get_homes

Get list of all homes under user account.

Parameters: None

Returns: Comma-separated list of home names. Returns empty string or appropriate message if no data

switch_home

Switch user's current operating home. After switching, subsequent device queries, controls, and other operations will target the newly switched home.

Parameters:

home_name (String, Required): Name of target home

Returns: Switch operation result message

Automation Configuration

automation_config

Automation configuration (currently supports only scheduled or delayed device control tasks).

Parameters:

scheduled_time (String, Required): Scheduled execution time using standard Crontab format "minute hour day month weekday". Examples: "30 14 * * *" (daily at 14:30), "0 9 * * 1" (Mondays at 9:00)
endpoint_ids (Array<Integer>, Required): List of device IDs for scheduled control
control_params (Object, Required): Device control parameters using same format as device_control tool (including action, attribute, value, etc.)
task_name (String, Required): Name or description of this automation task (for identification and management)
execution_once (Boolean, Optional): Whether to execute only once
- true: Execute task only once at specified time (default)
- false: Execute task periodically (daily, weekly, etc.)

Returns: Automation configuration result message

Project Structure

Directory Structure

.
├── cmd.go                # Cobra CLI command definitions and program entry point (contains main function)
├── server.go             # MCP server core logic, tool definitions, and request handling
├── smh.go                # Aqara smart home platform API interface wrapper
├── middleware.go         # Middleware: user authentication, timeout control, exception recovery
├── config.go             # Global configuration management and environment variable handling
├── go.mod                # Go module dependency management file
├── go.sum                # Go module dependency checksum file
├── readme/               # README documentation and image resources
│   ├── img/              # Image resources directory
│   └── *.md              # Multi-language README files
├── LICENSE               # MIT open source license
└── README.md             # Main project documentation

Core Files

cmd.go: Cobra framework-based CLI implementation defining run stdio and run http startup modes and main entry function
server.go: MCP server core implementation responsible for tool registration, request handling, and protocol support
smh.go: Aqara smart home platform API wrapper layer providing device control, authentication, and multi-home support
middleware.go: Request processing middleware providing authentication verification, timeout control, and exception handling
config.go: Global configuration management responsible for environment variable processing and API configuration

Development Guide

We welcome contributions through Issues and Pull Requests!

Before submitting code, please ensure:

Code follows Go language coding standards
Related MCP tools and interface definitions maintain consistency and clarity
Add or update unit tests to cover your changes
Update relevant documentation (such as this README) if necessary
Ensure your commit messages are clear and descriptive

🌟 If this project helps you, please give us a Star!

🤝 Welcome to join our community and make smart homes smarter together!

License

This project is licensed under the MIT License.

Aqara MCP Server Overview

What is Aqara MCP Server about?

How to use Aqara MCP Server?

Key Features

Use Cases

FAQ

Aqara MCP Server's README

Table of Contents

Features

How It Works

Quick Start

Prerequisites

Installation

Option 1: Download Pre-built Binaries (Recommended)

Option 2: Build from Source

Aqara Account Authentication

Client Configuration

Claude for Desktop Configuration Example

Configuration Parameters

Other MCP Clients

Starting the Service

Standard Mode (Recommended)

HTTP Mode (Coming Soon)

API Tools Reference

Device Control

device_control

Device Query

device_query

device_status_query

device_log_query

Scene Management

get_scenes

run_scenes

Home Management

get_homes

switch_home

Automation Configuration

automation_config

Project Structure

Directory Structure

Core Files

Development Guide

License

Aqara MCP Server Reviews

Login Required

Actions

Aqara MCP Server's Information

Similar MCP Servers like Aqara MCP Server

Zed

Everything

Git

Time

Cline

Continue

Context7 MCP

GitHub MCP Server

Daytona