aqara

The Aqara MCP Server exposes a set of MCP-compliant tools that bridge AI assistants with Aqara smart home devices. It supports core operations such as device_control for commanding devices, device_query and device_status_query for retrieving device information, and scene management functions like get_scenes and run_scenes. The server authenticates with Aqara through an API key and base URL, and implements MCP protocol endpoints so clients can send standardized requests to manage homes, query devices, and orchestrate automation tasks. Typical usage involves configuring an MCP client (for example a remote advisory client or an on-device assistant) to point at this server and then invoking the available MCP tools to read or control Aqara devices. The README outlines a remote deployment path and a local deployment path, both of which rely on the same underlying MCP tools and API surface.

In practice, you can leverage the core APIs to:

• Control devices with device_control (on/off, brightness, color temp, modes).
• Query devices and their statuses with device_query and device_status_query.
• Manage automation and scenes with automation_config, get_scenes, and run_scenes.
• Retrieve home configurations and switch between homes using get_homes and switch_home.

When using a client like Cursor or another MCP-enabled interface, you will typically configure the client to communicate with the Aqara MCP Server endpoint, supply your Aqara api_key in the Authorization header, and then perform requests that map to the MCP tools defined by the server. The server is designed to be cross-platform (Go), and can be built for various environments or run as a local binary or remote service depending on your deployment choice.

Prerequisites:

• Go 1.24+ installed on your system
• Git installed
• Optional: pre-built binaries or Docker, depending on preferred deployment method

Install from source (local deployment):

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

2. Resolve dependencies and build go mod tidy go build -ldflags="-s -w" -o aqara-mcp-server

3. Run the server ./aqara-mcp-server

Environment variables commonly used (see Quick Start for credentials):

• aqara_api_key: Your Aqara API key for authentication
• aqara_base_url: The base URL of the Aqara Cloud API

Alternative: Run via Docker (if a container image is provided by the project): docker run -d --name aqara-mcp-server -e aqara_api_key="YOUR_API_KEY" -e aqara_base_url="YOUR_BASE_URL" aqara/aqara-mcp-server:latest

Remote deployment (recommended for quick start):

• Follow the Quick Start Guide in the README to configure a remote MCP server in your MCP client (Cursor, etc.).

Tips and common considerations:

• Keep api_key confidential and rotate credentials as needed. Never commit credentials to version control.
• If running locally, ensure your environment variables are exported in the shell or defined in a startup script.
• When using remote MCP servers, ensure the client’s URL in the configuration points to the correct server endpoint and that the Authorization header carries a valid API key.
• The server follows MCP protocol; ensure your MCP client supports the required core tools listed in the API reference (device_control, device_query, device_status_query, get_scenes, run_scenes, get_homes, switch_home, automation_config).
• For Go builds, enabling optimizations (ldflags) helps reduce binary size and may improve startup time.
• If you encounter connectivity or authentication issues, verify base_url and api_key formatting, and check for firewall/proxy restrictions between the client and server.