Aqara Mcp Server

Aqara MCP 服务是由 Aqara Agent 提供的远程 MCP 服务。它让支持 MCP 的 AI 应用能够安全地连接 Aqara 智能家居功能。需要集成 MCP 时，请配置 Aqara Agent 提供的远程 MCP URL。

提示

推荐：Aqara Agent 官方 Skills

如果你的应用支持 Agent Skills（例如 Codex App、Cursor 或 OpenClaw），我们建议优先使用官方 Aqara Agent Skills。你可以通过自然语言查询和控制家庭／空间、设备、场景、自动化、能源消耗等，无需配置 MCP 服务。

• GitHub：aqara/aqara-agent-skills
• ClawHub：aqara/aqara-agent

目录

• 概览
• 功能
• 工作原理
• 快速开始
  • 前提条件
  • 步骤 1：账户认证
  • 步骤 2：配置远程 MCP
  • 步骤 3：验证
• 配置说明
• MCP 工具参考
  • 核心工具概览
  • 家庭和位置
  • 设备查询与控制
  • 场景
  • 自动化
  • 能源消耗
  • 灯光效果
  • 固件
  • 参数约定
• 许可证

概览

目前推荐的 MCP 集成以 Aqara Agent 为核心：

• 远程 MCP：适用于支持通过 https://agent.aqara.com/open/mcp 使用 Streamable HTTP 的应用。
• Aqara Agent Skills：适用于支持 Agent Skills 的应用——安装 Skills，无需手动配置 MCP 服务。
• MCP 工具功能：涵盖家庭／空间、设备、场景、自动化、能源消耗、灯光效果和固件等智能家居操作。

功能

• 🔍 灵活的设备查询：可按家庭／空间、设备类型或设备 ID 查询设备基本信息、实时状态和控制日志。
• ✨ 全面的设备控制：可控制 Aqara 设备的电源、亮度、色温、温度、风扇速度、模式、窗帘开合比例等。
• 🎬 智能场景管理：查询和运行场景，并查看场景执行历史。
• ⏰ 自动化查询：查询自动化规则及其执行历史。
• 📈 能源统计：按房间／空间或设备查询用电量和费用，并提供汇总和详细视图。
• 💡 灯光效果管理：查询灯光方案／效果、应用指定效果，并查询效果配置参数。
• 🔄 固件管理：查询当前和可用的固件版本，并启动设备固件升级。
• 🏠 多个家庭和空间：列出 Aqara 账户中的家庭以及当前家庭中的房间／空间。
• 🔌 远程 MCP 集成：通过 MCP URL 连接 Cursor 和 Codex App 等应用。
• 🔐 安全认证：登录 Aqara Agent 后获取 aqara_api_key——配置时请妥善保管凭据。

工作原理

在远程 MCP 模式下，应用通过 HTTP 连接到 Aqara Agent 的 MCP 服务，并附带在登录页面生成的 Bearer 令牌。Aqara Agent 会验证凭据、执行工具调用，并将结果返回给应用：

graph LR
    A[AI App / MCP host] --> B[Aqara Agent]
    B --> C[Aqara Cloud API]
    C --> D[Aqara Devices / Scenes / Automations]

1. AI 应用 / MCP 主机：用户通过 Cursor、Codex App 等类似应用发送自然语言指令。
2. Aqara Agent：验证用户凭据、解析并运行相应的工具。
3. Aqara Cloud API：对设备、场景、自动化、能耗、灯光效果、固件等执行数据查询或控制操作。

---

快速开始

前提条件

• 拥有注册了智能设备的 Aqara 账号。
• 使用 支持远程 MCP 的应用，例如 Cursor 或 Codex App。
• Aqara Agent 凭据：登录页面提供的 aqara_api_key 和 aqara_mcp_url。

步骤 1：账号验证

1. 打开登录页面： https://agent.aqara.com/login

2. 完成登录：

   • 使用 Aqara 账号登录。
   • 登录后，复制页面上显示的 aqara_api_key。
   • 配置 MCP 时，使用页面上的 aqara_mcp_url，通常为 https://agent.aqara.com/open/mcp。

3. 安全保存凭据：

   妥善保管 aqara_api_key。不要将其提交到代码仓库、发布在截图中或分享给他人。

   

步骤 2：配置远程 MCP

Cursor

1. 打开 Cursor Settings，前往 Tools & MCPs，然后点击 New MCP Server。

   

2. 添加远程 MCP 配置。使用登录页面上的 aqara_mcp_url；如果手动输入，请使用 /open/mcp 路径。

   {
     "mcpServers": {
       "aqara": {
         "type": "http",
         "url": "https://agent.aqara.com/open/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_AQARA_API_KEY>"
         }
       }
     }
   }
   

3. 保存配置并重启 Cursor，使 MCP 设置生效。

Codex App

1. 将登录页面上的 aqara_api_key 保存为环境变量。对于使用 zsh 的 macOS，在 ~/.zshrc 中添加以下内容：

   export AQARA_API_KEY="<YOUR_AQARA_API_KEY>"
   

2. 重启 Codex App，然后在 Settings 中连接到自定义 MCP。

3. 选择 Streamable HTTP。

4. 输入登录页面上的 aqara_mcp_url，例如 https://agent.aqara.com/open/mcp。

5. 在 Bearer token env var 中输入环境变量名称 AQARA_API_KEY，而不是 API 密钥本身。Codex App 会从此变量读取令牌。

步骤 3：验证

配置成功后，你可以使用以下自然语言请求进行测试：

User: Show all devices in my home
Assistant: Query the device list via MCP

User: Turn on the living room light
Assistant: Run device control via MCP

User: Run the movie night scene
Assistant: Run the scene via MCP

如果应用的 MCP 面板显示 Aqara 已连接且可见 Aqara 工具，则说明配置已生效。

---

配置说明

• MCP URL 请使用 https://agent.aqara.com/open/mcp 或登录页面上的 aqara_mcp_url，不要将登录页面 URL 用作 MCP URL。
• 设备控制、场景执行和固件升级工具会影响实际的家庭设备。首次使用时，请先运行查询工具，以确认家庭、空间、设备和场景信息。
• 如果连接失败，请检查：MCP 类型是否为 Streamable HTTP、URL 是否包含 /open/mcp、凭据是否过期，以及配置更改后是否已重启应用或重新加载 MCP。

---

MCP 工具参考

以下工具列表基于当前 Aqara Agent 服务中注册的函数定义。应用在 UI 中显示的工具名称可能不同，但参数含义和功能范围保持一致。

核心工具概览

工具类别	工具	描述
家庭和位置	all_homes_inquiry, position_base_inquiry	查询家庭和房间／空间信息
设备查询与控制	device_base_inquiry, device_status_inquiry, device_status_control, fuzzy_device_batch_control, device_log_inquiry	查询设备基本信息和实时状态、控制设备并查看控制日志
场景	scene_base_inquiry, scene_run, scene_execution_history_inquiry	查询并运行场景，以及查询场景执行历史
自动化	automation_base_inquiry, automation_execution_history_inquiry	查询自动化规则和执行历史
能耗	energy_consumption_inquiry_for_position, energy_consumption_inquiry_for_device	按房间／空间或设备查询用电量／电费
灯光效果	lighting_effect_inquiry, device_lighting_effect_inquiry, lighting_effect_control, lighting_effect_config_params_inquiry	查询并应用灯光效果，以及查询效果配置参数
固件	device_firmware_inquiry, device_firmware_upgrade	查询并升级设备固件

家庭和位置

all_homes_inquiry

查询当前 Aqara 账户下的所有家庭。

参数： 无

返回： 家庭列表，包含家庭名称、家庭 ID 和相关字段。

position_base_inquiry

查询当前家庭中所有房间／空间的基本信息。

参数： 无

返回： 房间／空间列表，包含位置名称、位置 ID 和相关字段。

设备查询与控制

device_base_inquiry

按房间／空间和设备类型查询设备基本信息，不包含实时状态。

参数：

• position_ids (Array<String>, optional)：房间／空间 ID 列表。为空时不应用位置筛选。
• device_types (Array<String>, optional)：设备类型，例如 Light、Switch、Outlet、AirConditioner、WindowCovering、Camera。为空时不应用设备类型筛选。

返回： 设备基本信息列表，包括设备名称、设备 ID、位置和设备类型。

device_status_inquiry

查询设备的实时状态，例如电源、亮度、色温、温度、风扇速度和模式。

参数：

• device_ids (Array<String>, optional)：设备 ID。提供时优先按设备 ID 查询。
• position_ids (Array<String>, optional)：房间／空间 ID。
• device_types (Array<String>, optional)：设备类型。

返回： 设备状态列表，包含当前可读取的值。

device_status_control

控制指定设备的状态或属性，例如电源、亮度、色温、温度、风扇速度、模式和窗帘百分比。

参数：

• device_ids (Array<String>, required)：目标设备 ID。
• attribute (String, required)：要控制的属性，例如 on_off、brightness、color_temperature、temperature、percentage、mode。
• action (String, required)：控制操作，例如 on、off、set、up、down、warmer、cooler、start、stop。
• value (String, optional)：目标值，例如 50、max、min、cool、heat、red。

返回： 设备控制执行结果。

fuzzy_device_batch_control

按房间／空间和设备类型批量控制设备，例如“关闭所有灯”“关闭客厅里的所有设备”或“将所有空调设为 26°”。

参数：

• position_ids (Array<String>, optional)：房间／空间 ID。为空时可能表示整个家庭。
• device_types (Array<String>, optional)：设备类型。
• attribute (String, required)：要控制的属性。
• action (String, required)：控制操作。
• value (String, optional)：目标值。

返回： 批量控制执行结果。

device_log_inquiry

查询指定时间范围内的设备控制日志，包括控制时间、内容和结果。

参数：

• time_range (Array<String>, optional): 时间间隔，例如 ["2026-01-01 00:00:00", "2026-01-01 23:59:59"]。
• device_ids (Array<String>, optional): 设备 ID。提供时，查询优先按设备 ID 进行。
• position_ids (Array<String>, optional): 房间／空间 ID。
• device_types (Array<String>, optional): 设备类型。

返回： 控制日志列表和实际查询的时间范围。

场景

scene_base_inquiry

查询场景基本信息，可按场景 ID、位置 ID 或设备 ID 筛选。

参数：

• scene_ids (Array<String>, optional): 场景 ID。提供时，查询优先按场景 ID 进行。
• position_ids (Array<String>, optional): 房间／空间 ID。
• device_ids (Array<String>, optional): 与设备相关的场景所对应的设备 ID。

返回： 场景基本信息列表。

scene_run

运行一个或多个指定场景。

参数：

• scene_ids (Array<String>, required): 要运行的场景 ID。

返回： 场景执行结果。

scene_execution_history_inquiry

查询指定时间范围内的场景执行历史。

参数：

• time_range (Array<String>, optional): 时间间隔。
• scene_ids (Array<String>, optional): 场景 ID。
• position_ids (Array<String>, optional): 房间／空间 ID。
• device_ids (Array<String>, optional): 设备 ID。

返回： 场景执行历史和实际查询的时间范围。

自动化

automation_base_inquiry

查询自动化规则基本信息，可按自动化 ID、位置 ID 或设备 ID 筛选。

参数：

• automation_ids (Array<String>, optional): 自动化 ID。提供时，查询优先按自动化 ID 进行。
• position_ids (Array<String>, optional): 房间／空间 ID。
• device_ids (Array<String>, optional): 与设备相关的自动化所对应的设备 ID。

返回： 自动化规则列表。

automation_execution_history_inquiry

查询指定时间范围内的自动化执行历史。

参数：

• time_range (Array<String>, optional): 时间间隔。
• automation_ids (Array<String>, optional): 自动化 ID。
• position_ids (Array<String>, optional): 房间／空间 ID。
• device_ids (Array<String>, optional): 设备 ID。

返回： 自动化执行历史和实际查询的时间范围。

能耗

energy_consumption_inquiry_for_position

按住宅／房间／空间查询用电量或电费，并提供汇总和明细视图。

参数：

• data_type (String, required): 查询类型——1 表示用电量，2 表示电费，3 表示两者。
• time_range (Array<String>, required): 时间间隔。
• time_gradient (String, optional): 粒度：30min、1hour、1day、1week、1month。
• data_aggregation_mode (String, optional): total = 汇总视图，detail = 明细视图。
• positions (Array<String>, optional): 房间／空间 ID。为空时，查询所有有效房间。

返回： 按房间／空间统计的用电量／电费。

energy_consumption_inquiry_for_device

按设备查询用电量或电费，可按位置或设备筛选，并提供汇总和明细视图。

参数：

• data_type (String, required): 1 = 用电量，2 = 电费，3 = 两者。
• time_range (Array<String>, required): 时间间隔。
• time_gradient (String, optional): 30min、1hour、1day、1week、1month。
• data_aggregation_mode (String, optional): total = 汇总视图，detail = 明细视图。
• positions (Array<String>, optional): 房间／空间 ID。
• device_ids (Array<String>, optional): 设备 ID。提供时，查询优先按设备进行。

返回： 按设备统计的用电量／电费。

灯光效果

lighting_effect_inquiry

查询家中的可用灯光场景/效果。

参数： 无

返回： 效果列表，包含名称和适用的控制范围。

device_lighting_effect_inquiry

查询每台设备支持的灯光效果名称。

参数：

• device_ids (Array<String>, required): 要查询效果的设备 ID。

返回： 设备与效果名称的映射列表。

lighting_effect_control

将指定的灯光效果应用于目标设备或房间/空间。

参数：

• effect_name (String, required): 效果名称。
• device_ids (Array<String>, optional): 目标设备 ID。提供此参数时，优先控制设备。
• position_ids (Array<String>, optional): 房间/空间 ID。

返回： 灯光效果控制执行结果。

lighting_effect_config_params_inquiry

查询灯具设备配置灯光效果所需的参数。

参数：

• device_ids (Array<String>, required): 目标灯具设备 ID。

返回： 效果配置参数，包括可配置项、取值范围和已保存的用户效果。

固件

device_firmware_inquiry

批量查询设备的当前固件版本和可用升级版本。

参数：

• device_ids (Array<String>, optional): 设备 ID。提供此参数时，优先查询设备。
• position_ids (Array<String>, optional): 房间/空间 ID。
• device_types (Array<String>, optional): 设备类型。

返回： 固件信息，包括设备名称、在线状态、当前版本和可用版本。

device_firmware_upgrade

根据设备、位置或类型筛选符合条件的设备，并开始固件升级。

参数：

• device_ids (Array<String>, optional): 设备 ID。提供此参数时，优先升级这些设备。
• position_ids (Array<String>, optional): 房间/空间 ID。
• device_types (Array<String>, optional): 设备类型。

返回： 固件升级提交结果。

参数约定

• position_ids / positions：房间/空间 ID 列表；省略时，查询或控制范围遵循各工具的说明。
• device_ids：设备 ID 或设备端点 ID 列表，通过客户端识别和服务端映射进行解析。
• device_types：设备类型，例如 Light、Switch、Outlet、AirConditioner、WindowCovering、Camera、TemperatureSensor。
• attribute：控制属性，例如 on_off、brightness、color_temperature、temperature、wind_speed、mode、percentage、volume、color。
• action：控制操作，例如 on、off、set、up、down、warmer、cooler、start、stop、pause、resume。
• value：目标值，例如 50、100、max、min、red、cool、heat、灯光效果名称。
• time_range：时间区间数组，通常为 ["YYYY-MM-DD HH:MM:SS", "YYYY-MM-DD HH:MM:SS"]。
• data_type：能耗查询类型——1 = 用电量，2 = 电费，3 = 两者。
• time_gradient：能耗统计粒度：30min、1hour、1day、1week、1month。
• data_aggregation_mode：能耗聚合模式——total = 汇总，detail = 详细视图。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

---

版权所有 © 2025 Aqara-Agent。保留所有权利。