Aqara MCP Server

Aqara MCP Server

英语| 中文 | 繁体中文 | 法语 | 韩语 | 西班牙语 | 日本语 | 德语 | 意大利语

 ](https://golang.org/dl/)   

Aqara MCP服务器 是基于 模型上下文协议（MCP）该平台实现了人工智能助手（如Claude、Cursor等）与Aqara智能家居生态系统的无缝集成。

\[！提示\] 推荐：官方阿卡拉特工技能 如果您的AI主机支持代理技能（如Claude、Cursor、OpenClaw等），我们 强烈推荐 使用官方 阿卡拉特工技能 直接——无需部署自己的MCP服务器。通过自然语言，开箱即用地查询和控制家庭/空间、设备、场景、自动化和能源使用。 - 🔗 github： aqara/aqara代理技能 - 🔗 ClawHub： aqara/aqara试剂

目录

• 目录
• 特性
• 运作原理
• 快速开始

- 先决条件 - 步骤1：帐户身份验证 - 第二步：如何使用 - 选项A：远程MCP服务器（推荐） - 选项B：本地MCP服务器 - 步骤3：验证

• API 参考

- 核心工具概述 - 设备控制API - device_control - 设备查询API - device_query - device_status_query - device_log_query - 场景管理API - get_scenes - run_scenes - 首页管理API - get_homes - switch_home - 自动化配置API - automation_config

• 项目结构

- 目录结构 - 核心文件描述

• 发展与贡献

- 开发环境设置 - 代码质量标准 - 贡献指南

• 许可证

特性

• ✨ 设备综合控制：对Aqara智能设备的各种属性进行细粒度控制，包括开/关、亮度、色温和模式。
• 🔍 灵活的设备查询：能够按房间或设备类型查询设备列表及其详细状态。
• 🎬 智能场景管理：支持查询和执行用户预定义的智能家居场景。
• 📈 设备历史记录：查询指定时间范围内设备的历史状态变化记录。
• ⏰ 自动化配置：支持配置计划或延迟的设备控制任务。
• 🏠 多家庭支持：支持用户帐户下不同家庭之间的查询和切换。
• 🔌 MCP协议兼容性：完全符合MCP规范，可轻松与各种AI助手集成。
• 🔐 安全认证：利用基于登录授权+签名的安全机制来保护用户数据和设备安全。
• 🌐 交叉平台的：用Go开发，可以编译成多个平台的可执行文件。
• 🔧 易于扩展：模块化设计允许方便地添加新工具和功能。

运作原理

Aqara MCP服务器充当AI助手和Aqara智能家居平台之间的桥梁：

graph LR
    A[AI Assistant - MCP Host] --> B[MCP Client]
    B --> C[Aqara MCP Server]
    C --> D[Aqara Cloud API]
    D --> E[AIOT Devices]

1. AI助手：用户通过AI助手发出命令（例如，“打开客厅灯”）。
2. MCP客户端：解析用户的命令并调用Aqara MCP服务器提供的相应工具（例如。， device_control)根据MCP协议。
3. Aqara MCP服务器（本项目）：接收客户端的请求，使用配置的Aqara凭据与Aqara Cloud API进行通信，并执行实际的设备操作或数据查询。
4. 响应流：Aqara Cloud API返回结果，该结果通过Aqara MCP服务器传递回MCP客户端，并最终呈现给用户。

______________________________________________________________________

快速开始

先决条件

• Aqara账户 注册的智能设备。
• 启用MCP的客户端 （例如，Claude代表桌面、光标）。
• 转到1.24+ （仅需要从源进行本地部署）。

步骤1：帐户身份验证

无论部署模式如何，您首先都需要获取Aqara身份验证凭据：

1. 访问登录页面:

🔗 https://cdn.aqara.com/app/mcpserver/login.html

1. 完成登录过程:

- 使用您的Aqara凭据登录。 - 获取 api_key 和 base_url.

1. 安全地存储凭据:

> ⚠️ 请保留您的 api_key 信息安全，不要泄露给他人。

Configuration Example

第二步：如何使用

选择适合您需求的部署方法：

选项A：远程MCP服务器（推荐）

适用于：希望在不设置本地环境的情况下快速入门的用户。

优势:

• ✅ 随时可用：无需下载或编译；直接配置和使用。
• ✅ 自动更新：服务器会自动维护和更新。
• ✅ 高可用性：专业操作确保服务稳定。
• ✅ 多平台兼容性：没有操作系统限制。

配置MCP客户端:

1. 打开设置:

- 启动光标。

Open Setting

1. 添加服务器配置:

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

1. 重新启动应用程序:

- 重新启动Cursor以使更改生效。

选项B：本地MCP服务器

适用于：需要数据主权、自定义配置或离线使用的用户。

优势:

• ✅ 数据隐私：所有数据都在本地处理。
• ✅ 完全控制：可定制的配置和可扩展的功能。
• ✅ 离线可用性：基本功能不受网络中断的影响。
• ✅ 无限制：不受云服务的限制。

安装步骤:

1. 下载程序 （选择一个）：

推荐：下载预编译版本

访问 下载适用于您的操作系统的最新版本。

或者：从源代码构建

   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

1. 设置环境变量:

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

配置MCP客户端（例如。， Claude桌面版):

1. 打开设置:

- 启动克劳德桌面版。 - 导航到：设置→ 开发商。

Claude Open Setting

1. 编辑配置文件:

- 单击“编辑配置”。

Claude Edit Configuration

1. 添加服务器配置（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"
         }
       }
     }
   }

1. 重新启动应用程序:

- 重新启动Claude for Desktop以使更改生效。

步骤3：验证

使用以下测试命令验证配置是否成功：

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]

如果你看到类似“🔧 连接到Aqara MCP服务器，“配置成功！

______________________________________________________________________

API 参考

核心工具概述

设备控制API

device_control

控制智能家居设备的状态或属性（例如，开/关、温度、亮度、颜色、色温）。

参数：

• endpoint_ids _（数组\，必填）_：要控制的设备ID列表。
• control_params _（对象，必填）_：包含特定操作的控制参数对象：

- action _（字符串，必填）_：要执行的动作（例如。， "on", "off", "set", "up", "down", "cooler", "warmer"). - attribute _（字符串，必填）_：要控制的设备属性（例如。， "on_off", "brightness", "color_temperature", "ac_mode"). - value _（字符串|数字，可选）_：目标值（需要时 action 是“设置”）。 - unit _（字符串，可选）_：值的单位（例如。， "%", "K", "℃").

退货： 指示设备控制操作结果的消息。

设备查询API

device_query

根据指定的位置（房间）和设备类型检索设备的完整列表，并支持过滤（不包括实时状态信息）。

参数：

• positions _（数组\，可选）_：房间名称列表。空数组查询所有房间。
• device_types _（数组\，可选）_：设备类型列表（例如。， "Light", "WindowCovering", "AirConditioner", "Button").空数组查询所有类型。

退货： Markdown格式的设备列表，包括设备名称和ID。

device_status_query

获取设备的当前状态信息（用于查询颜色、亮度、开/关等实时状态）。

参数：

• positions _（数组\，可选）_：房间名称列表。空数组查询所有房间。
• device_types _（数组\，可选）_：设备类型列表。与相同的选项 device_query。空数组查询所有类型。

退货： Markdown格式的设备状态信息。

device_log_query

查询设备的历史日志信息。

参数：

• endpoint_ids _（数组\，必填）_：要查询历史记录的设备ID列表。
• start_datetime _（字符串，可选）_：中的查询开始时间 YYYY-MM-DD HH:MM:SS 格式（例如。， "2023-05-16 12:00:00").
• end_datetime _（字符串，可选）_：中的查询结束时间 YYYY-MM-DD HH:MM:SS 格式。
• attributes _（数组\，可选）_：要查询的设备属性名称列表（例如。， ["on_off", "brightness"]).如果没有提供，则查询所有记录的属性。

退货： Markdown格式的历史设备状态信息。

场景管理API

get_scenes

查询用户家中的所有场景或指定房间中的场景。

参数：

• positions _（数组\，可选）_：房间名称列表。一个空数组查询整个家庭的场景。

退货： Markdown格式的场景信息。

run_scenes

按场景ID执行指定的场景。

参数：

• scenes _（数组\，必填）_：要执行的场景ID列表。

退货： 指示场景执行结果的消息。

首页管理API

get_homes

获取用户帐户下所有房屋的列表。

参数： 无

退货： 以逗号分隔的家庭名称列表。如果没有可用数据，则返回空字符串或相应的消息。

switch_home

切换用户当前活动的主页。切换后，后续的设备查询、控制等将针对新切换的家庭。

参数：

• home_name _（字符串，必填）_：目标房屋的名称。

退货： 指示切换操作结果的消息。

自动化配置API

automation_config

配置自动化（目前仅支持计划或延迟的设备控制任务）。

参数：

• scheduled_time _（字符串，必填）_：标准Crontab格式的计划执行时间 "min hour day month week"例如。， "30 14 * * *" （每天14:30执行）， "0 9 * * 1" （每周一9:00执行）。
• endpoint_ids _（数组\，必填）_：要按计划控制的设备ID列表。
• control_params _（对象，必填）_：设备控制参数，格式与 device_control 工具（包括动作、属性、值等）。
• task_name _（字符串，必填）_：此自动化任务的名称或描述（用于识别和管理）。
• execution_once _（布尔值，可选）_：是否只执行一次。

- true：在指定时间只执行一次任务（默认）。 - false：定期执行任务（例如，每天、每周）。

退货： 指示自动化配置结果的消息。

项目结构

目录结构

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

核心文件描述

• cmd.go：基于Cobra框架的CLI实现，定义 run stdio 和 run http 启动模式和主进入功能。
• server.go：核心MCP服务器实现，负责工具注册、请求处理和协议支持。
• smh.go：Aqara智能家居平台API包装层，提供设备控制、身份验证和多家庭支持。
• middleware.go：请求处理中间件，提供身份验证、超时控制和异常处理。
• config.go：全局配置管理，负责处理环境变量和API配置。

发展与贡献

开发环境设置

# 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

代码质量标准

• Go语言：遵循官方Go编码标准。
• 文档：全面的API文档。
• 测试：至少80%的代码覆盖率。
• 安全：定期安全审计。

贡献指南

1. 分叉存储库
2. 创建要素分支: git checkout -b feature/amazing-feature
3. 提交您的更改: git commit -m 'Add some amazing feature'
4. 推到分支: git push origin feature/amazing-feature
5. 打开拉取请求

______________________________________________________________________

许可证

该项目根据 MIT许可证 -看看 许可证 文件以获取详细信息。

______________________________________________________________________

版权所有©2025 Aqara Copilot。保留所有权利。