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.

• 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

• ✨ 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

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]

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

• 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.)

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

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.

# 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.

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.

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

1. Open Claude for Desktop Settings

   

2. Switch to the Developer tab, then click Edit Config to open the configuration file in a text editor

   

3. 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"
         }
       }
     }
   }

   

• 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)

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)

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"

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

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

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

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

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

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

Execute specified scenes by scene ID.

Parameters:

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

Returns: Scene execution result message

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

.
├── 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

• 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

We welcome contributions through Issues and Pull Requests!

Before submitting code, please ensure:

1. Code follows Go language coding standards
2. Related MCP tools and interface definitions maintain consistency and clarity
3. Add or update unit tests to cover your changes
4. Update relevant documentation (such as this README) if necessary
5. 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!

This project is licensed under the MIT License.

Copyright (c) 2025 Aqara-Copilot