home / mcp / aqara mcp server

Aqara MCP Server

Provides MCP access to Aqara devices for device control, queries, scenes, and automation through MCP-enabled clients.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aqara-aqara-mcp-server": {
      "url": "https://[mcp-server-domain]/echo/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE",
        "aqara_api_key": "YOUR_API_KEY_HERE",
        "aqara_base_url": "https://api.aqara.com"
      }
    }
  }
}

Aqara MCP Server provides a Model Context Protocol (MCP) bridge between AI assistants and Aqara smart home devices. It enables you to control devices, query status, manage scenes, and configure automations through MCP-compatible clients in a secure, cross-platform Go-based server.

How to use

You use the Aqara MCP Server by connecting an MCP client (such as Claude or Cursor) to either a remote MCP service or a locally hosted server. Once connected, you can issue commands like turning devices on or off, querying device status, running scenes, or scheduling automated actions. The server handles authentication with Aqara and communicates with the Aqara Cloud API to perform the requested operations. You can switch between multiple homes, query devices by room or type, and view historical device logs as needed.

How to install

Prerequisites include a working Aqara account with registered devices and an MCP-enabled client for your workflow. The server can be used as a remote service or run locally from source. For local deployment you need Go 1.24+.

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

# Install dependencies
go mod tidy

# Build the executable
go build -ldflags="-s -w" -o aqara-mcp-server

# Run the server in stdio (local) mode
./aqara-mcp-server run stdio

Configuration and operation notes

There are two deployment patterns you can follow: remote MCP server (recommended for quick start) or local MCP server (for data sovereignty and customization). The remote pattern uses an online MCP endpoint, while the local pattern runs the server on your machine and connects to Aqara services using your credentials.

Remote MCP server configuration exposes an HTTP MCP endpoint to your MCP client. The client should point to the remote URL and pass your API key in the Authorization header.

Local MCP server requires you to run the server binary locally and provide credentials via environment variables. You then configure your MCP client to connect to your local endpoint.

Verification

After configuring either deployment method, perform simple checks to ensure connectivity and operation. For example, request a list of devices, turn on a specific device, and run a scene to verify end-to-end execution.

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]

Available tools

device_control

Direct device operations such as turning on/off, adjusting brightness, changing color temperature, and setting modes.

device_query

Query lists of devices by room or device type without real-time status.

device_status_query

Retrieve current real-time status for devices, including attributes like on/off, brightness, and color.

device_log_query

Query historical status changes for devices within a specified time window.

get_scenes

List available scenes in your homes.

run_scenes

Execute specified scenes by IDs to automate actions.

get_homes

Retrieve homes associated with your account.

switch_home

Switch the active home for subsequent queries and controls.

automation_config

Configure scheduled or delayed device control tasks.