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?

1. Prerequisites: Go 1.24+ (only if building from source), Git, an Aqara account with registered devices, and an MCP‑compatible client.
2. 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
     

3. Account Authentication: Open https://cdn.aqara.com/app/mcpserver/login.html, log in, and copy the generated token and region.
4. 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.
5. 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.

English | 中文 | 繁體中文 | Français | 한국어 | Español | 日本語 | Deutsch | Italiano

Aqara MCP Server is a smart home automation control service built on the Model Context Protocol (MCP). This platform enables seamless integration between AI assistants (like Claude, Cursor, etc.) and the Aqara smart home ecosystem.

Table of Contents

• Table of Contents
• Features
• How It Works
• Quick Start
  • Prerequisites
  • Step 1: Account Authentication
  • Step 2: How to Use
    • Option A: Remote MCP Server (Recommended)
    • Option B: Local MCP Server
  • Step 3: Verification
• API Reference
  • Core Tools Overview
  • Device Control API
    • device_control
  • Device Query API
    • device_query
    • device_status_query
    • device_log_query
  • Scene Management API
    • get_scenes
    • run_scenes
  • Home Management API
    • get_homes
    • switch_home
  • Automation Configuration API
    • automation_config
• Project Structure
  • Directory Structure
  • Core File Descriptions
• Development & Contribution
  • Development Environment Setup
  • Code Quality Standards
  • Contribution Guidelines
• License

Features

• ✨ Comprehensive Device Control: Fine-grained control over various attributes of Aqara smart devices, including on/off, brightness, color temperature, and modes.
• 🔍 Flexible Device Query: Ability to query device lists and their detailed statuses by room or device type.
• 🎬 Smart Scene Management: Supports querying and executing user-predefined smart home scenes.
• 📈 Device History: Query the historical status change records of devices within a specified time range.
• ⏰ Automation Configuration: Supports configuring scheduled or delayed device control tasks.
• 🏠 Multi-Home Support: Supports querying and switching between different homes under a user's account.
• 🔌 MCP Protocol Compatibility: Fully compliant with the MCP specification, allowing for easy integration with various AI assistants.
• 🔐 Secure Authentication: Utilizes a login authorization + signature-based security mechanism to protect user data and device security.
• 🌐 Cross-Platform: Developed in Go, can be compiled into executables for multiple platforms.
• 🔧 Easily Extensible: Modular design allows for the convenient addition of new tools and features.

How It Works

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

1. AI Assistant: The user issues a command through an AI assistant (e.g., "Turn on the living room light").
2. MCP Client: Parses the user's command and calls the corresponding tool provided by the Aqara MCP Server (e.g., device_control) according to the MCP protocol.
3. Aqara MCP Server (This Project): Receives the request from the client, communicates with the Aqara Cloud API using the configured Aqara credentials, and executes the actual device operation or data query.
4. Response Flow: The Aqara Cloud API returns the result, which is passed back to the MCP client via the Aqara MCP Server and finally presented to the user.

Quick Start

Prerequisites

• Aqara Account with registered smart devices.
• MCP-enabled Client (e.g., Claude for Desktop, Cursor).
• Go 1.24+ (only required for local deployment from source).

Step 1: Account Authentication

Regardless of the deployment mode, you first need to obtain Aqara authentication credentials:

1. Visit the Login Page: 🔗 https://cdn.aqara.com/app/mcpserver/login.html

2. Complete the Login Process:

   • Log in with your Aqara credentials.
   • Obtain the api_key and base_url.

3. Store Credentials Securely:

   ⚠️ Please keep your api_key information safe and do not disclose it to others.

   

Step 2: How to Use

Choose the deployment method that suits your needs:

Option A: Remote MCP Server (Recommended)

Suitable for: Users who want to get started quickly without local environment setup.

Advantages:

• ✅ Ready to Use: No need to download or compile; configure and use directly.
• ✅ Automatic Updates: The server is automatically maintained and updated.
• ✅ High Availability: Professional operations ensure service stability.
• ✅ Multi-Platform Compatibility: No operating system restrictions.

Configure MCP Client:

1. Open Settings:

   • Launch Cursor.

   

2. Add Server Configuration:

   {
     "mcpServers": {
       "aqara": {
         "type": "http",
         "url": "https://[mcp-server-domain]/echo/mcp",  // base_url
         "headers": {
           "Authorization": "Bearer [YOUR_API_KEY_HERE]"  // api_key
         }
       }
     }
   }
   

3. Restart the Application:

   • Restart Cursor for the changes to take effect.

Option B: Local MCP Server

Suitable for: Users who require data sovereignty, custom configurations, or offline use.

Advantages:

• ✅ Data Privacy: All data is processed locally.
• ✅ Full Control: Customizable configuration and extensible features.
• ✅ Offline Availability: Basic functions are not affected by network interruptions.
• ✅ No Restrictions: Not limited by cloud services.

Installation Steps:

1. Download the Program (choose one):

   Recommended: Download Pre-compiled Version

   Visit GitHub Releases to download the latest version for your operating system.

   Alternatively: Build from Source

   git clone https://github.com/aqara/aqara-mcp-server.git
   cd aqara-mcp-server
   go mod tidy
   go build -ldflags="-s -w" -o aqara-mcp-server
   

2. Set Environment Variables:

   export aqara_api_key="your_api_key_here"
   export aqara_base_url="your_base_url_here"
   

Configure MCP Client (e.g., Claude for Desktop):

1. Open Settings:

   • Launch Claude for Desktop.
   • Navigate to: Settings → Developer.

   

2. Edit Configuration File:

   • Click "Edit Configuration".

   

3. Add Server Configuration (claude_desktop_config.json):

   {
     "mcpServers": {
       "aqara": {
         "command": "/path/to/aqara-mcp-server",
         "args": ["run", "stdio"],
         "env": {
           "aqara_api_key": "your_api_key_here",
           "aqara_base_url": "your_base_url_here"
         }
       }
     }
   }
   

4. Restart the Application:

   • Restart Claude for Desktop for the changes to take effect.

Step 3: Verification

Use the following test commands to verify that the configuration is successful:

User: "Show all devices in my home"
Assistant: [Queries device list via MCP]

User: "Turn on the living room light"
Assistant: [Executes device control via MCP]

User: "Run the evening scene"
Assistant: [Executes scene via MCP]

If you see a message like "🔧 Connected to Aqara MCP Server," the configuration is successful!

API Reference

Core Tools Overview

Device Control API

device_control

Controls the state or attributes of smart home devices (e.g., on/off, temperature, brightness, color, color temperature).

Parameters:

• endpoint_ids (Array<Integer>, required): A list of device IDs to be controlled.
• control_params (Object, required): A control parameter object containing specific actions:
  • action (String, required): The action to perform (e.g., "on", "off", "set", "up", "down", "cooler", "warmer").
  • attribute (String, required): The device attribute to control (e.g., "on_off", "brightness", "color_temperature", "ac_mode").
  • value (String | Number, optional): The target value (required when action is "set").
  • unit (String, optional): The unit of the value (e.g., "%", "K", "℃").

Returns: A message indicating the result of the device control operation.

Device Query API

device_query

Retrieves a comprehensive list of devices based on specified locations (rooms) and device types, with support for filtering (does not include real-time status information).

Parameters:

• positions (Array<String>, optional): A list of room names. An empty array queries all rooms.
• device_types (Array<String>, optional): A list of device types (e.g., "Light", "WindowCovering", "AirConditioner", "Button"). An empty array queries all types.

Returns: A Markdown-formatted list of devices, including device names and IDs.

device_status_query

Gets the current status information of devices (used to query real-time status like color, brightness, on/off).

Parameters:

• positions (Array<String>, optional): A list of room names. An empty array queries all rooms.
• device_types (Array<String>, optional): A list of device types. Same options as device_query. An empty array queries all types.

Returns: Markdown-formatted device status information.

device_log_query

Queries the historical log information of devices.

Parameters:

• endpoint_ids (Array<Integer>, required): A list of device IDs for which to query history.
• start_datetime (String, optional): The query start time in YYYY-MM-DD HH:MM:SS format (e.g., "2023-05-16 12:00:00").
• end_datetime (String, optional): The query end time in YYYY-MM-DD HH:MM:SS format.
• attributes (Array<String>, optional): A list of device attribute names to query (e.g., ["on_off", "brightness"]). If not provided, all logged attributes are queried.

Returns: Markdown-formatted historical device status information.

Scene Management API

get_scenes

Queries all scenes in a user's home or scenes in specified rooms.

Parameters:

• positions (Array<String>, optional): A list of room names. An empty array queries scenes for the entire home.

Returns: Markdown-formatted scene information.

run_scenes

Executes specified scenes by their scene IDs.

Parameters:

• scenes (Array<Integer>, required): A list of scene IDs to be executed.

Returns: A message indicating the result of the scene execution.

Home Management API

get_homes

Gets a list of all homes under the user's account.

Parameters: None

Returns: A comma-separated list of home names. Returns an empty string or a corresponding message if no data is available.

switch_home

Switches the user's currently active home. After switching, subsequent device queries, controls, etc., will target the newly switched home.

Parameters:

• home_name (String, required): The name of the target home.

Returns: A message indicating the result of the switch operation.

Automation Configuration API

automation_config

Configures automation (currently only supports scheduled or delayed device control tasks).

Parameters:

• scheduled_time (String, required): The scheduled execution time in standard Crontab format "min hour day month week". E.g., "30 14 * * *" (execute at 14:30 every day), "0 9 * * 1" (execute at 9:00 every Monday).
• endpoint_ids (Array<Integer>, required): A list of device IDs to be controlled on a schedule.
• control_params (Object, required): Device control parameters, in the same format as the device_control tool (including action, attribute, value, etc.).
• task_name (String, required): The name or description of this automation task (for identification and management).
• execution_once (Boolean, optional): Whether to execute only once.
  • true: Executes the task only once at the specified time (default).
  • false: Executes the task periodically (e.g., daily, weekly).

Returns: A message indicating the result of the automation configuration.

Project Structure

Directory Structure

.
├── cmd.go                # Cobra CLI command definitions and program entry point (contains main function)
├── server.go             # Core MCP server logic, tool definitions, and request handling
├── smh.go                # Aqara smart home platform API interface wrapper
├── middleware.go         # Middleware: user authentication, timeout control, panic 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 documents and image resources
│   ├── img/              # Image resource directory
│   └── *.md              # Multi-language README files
├── LICENSE               # MIT open source license
└── README.md             # Main project document

Core File Descriptions

• cmd.go: CLI implementation based on the Cobra framework, defining run stdio and run http start modes and the main entry function.
• server.go: Core MCP server 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 handling middleware, providing authentication validation, timeout control, and exception handling.
• config.go: Global configuration management, responsible for handling environment variables and API configuration.

Development & Contribution

Development Environment Setup

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

# Install dependencies
go mod tidy

# Run tests
go test ./...

# Optimized build
go build -ldflags="-s -w" -o aqara-mcp-server

Code Quality Standards

• Go Language: Follows official Go coding standards.
• Documentation: Comprehensive API documentation.
• Testing: Minimum 80% code coverage.
• Security: Regular security audits.

Contribution Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add some amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright © 2025 Aqara-Copilot. All rights reserved.