README - aqara-mcp-server by aqara

Aqara MCP Server

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.

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 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"

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 .

aqara/aqara-mcp-server

Aqara MCP Server

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