AI导哈

智能家居远程控制服务

Aqara MCP Server 是一个远程MCP服务，允许支持MCP的AI应用安全连接到Aqara智能家居功能，提供设备查询与控制、场景管理、自动化规则查询、能源统计等功能。

  • by aqara
  • 云端部署
  • 48 星标
  • 更新于
在 GitHub 查看 aqara/aqara-mcp-server

使用说明

Aqara MCP Server

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

Aqara MCP服务器 是由Aqara代理提供的远程MCP服务。它允许启用MCP的AI应用程序安全地连接到Aqara智能家居功能。当您需要MCP集成时，请配置Aqara代理提供的远程MCP URL。

[！提示] 推荐：官方阿卡拉特工技能

如果您的应用程序支持代理技能（如Codex App、Cursor或OpenClaw），我们建议您使用官方 阿卡拉特工技能 第一。您可以用自然语言查询和控制家庭/空间、设备、场景、自动化、能耗等，而无需配置MCP服务器。

目录

概述

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

  • 远程MCP：适用于支持Streamable HTTP的应用程序 https://agent.aqara.com/open/mcp.
  • 阿卡拉特工技能：对于具有代理技能的应用程序，无需手动配置MCP服务器即可安装技能。
  • MCP工具功能：涵盖家庭/空间、设备、场景、自动化、能耗、照明效果和固件的智能家居操作。

特征

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

运作原理

在远程MCP模式下，应用程序通过HTTP连接到Aqara代理的MCP服务，并包含在登录页面上生成的承载令牌。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. 阿卡拉特工：验证用户凭据，解释并运行相应的工具。
  3. Aqara Cloud API：对设备、场景、自动化、能耗、照明效果、固件等执行数据查询或控制操作。

快速开始

先决条件

  • 一 Aqara账户 注册的智能设备。
  • 一 支持远程MCP的应用程序，例如游标或Codex应用程序。
  • Aqara代理凭据: 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

光标

  1. 打开光标设置，转到 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应用程序

  1. 保存 aqara_api_key 从登录页面作为环境变量。对于带有zsh的macOS，请添加以下内容 ~/.zshrc:

    export AQARA_API_KEY="<YOUR_AQARA_API_KEY>"

  2. 重新启动Codex应用程序，然后在“设置”中连接到自定义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工具可见，则配置处于活动状态。

配置说明

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

MCP工具参考

下面的工具列表基于当前Aqara代理服务上注册的函数定义。应用程序可以在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 （数组<String>，可选）：房间/空间ID列表。当为空时，不应用位置过滤器。
  • device_types （数组<String>，可选）：设备类型，例如。 Light, Switch, Outlet, AirConditioner, WindowCovering, Camera。当为空时，不应用设备类型过滤器。

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

device_status_inquiry

查询实时设备状态，如功率、亮度、色温、温度、风扇速度和模式。

参数：

  • device_ids （数组<String>，可选）：设备ID。提供时，查询会优先考虑设备ID。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_types （数组<String>，可选）：设备类型。

退货： 具有当前可读值的设备状态列表。

device_status_control

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

参数：

  • device_ids （数组<String>，必填）：目标设备ID。
  • attribute （字符串，必填）：控制属性，例如。 on_off, brightness, color_temperature, temperature, percentage, mode.
  • action （字符串，必填）：控制动作，例如。 on, off, set, up, down, warmer, cooler, start, stop.
  • value （字符串，可选）：目标值，例如。 50, max, min, cool, heat, red.

退货： 设备控制执行结果。

fuzzy_device_batch_control

按房间/空间和设备类型批量控制设备，例如“关闭所有灯”、“关闭客厅的所有东西”或“将所有空调机组设置为26°”

参数：

  • position_ids （数组<String>，可选）：房间/空间ID。空的时候，可能意味着整个家。
  • device_types （数组<String>，可选）：设备类型。
  • attribute （字符串，必填）：属性为控件。
  • action （字符串，必填）：控制动作。
  • value （字符串，可选）：目标值。

退货： 批量控制执行结果。

device_log_inquiry

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

参数：

  • time_range （数组<String>，可选）：时间间隔，例如。 ["2026-01-01 00:00:00", "2026-01-01 23:59:59"].
  • device_ids （数组<String>，可选）：设备ID。提供时，查询会优先考虑设备ID。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_types （数组<String>，可选）：设备类型。

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

场景

scene_base_inquiry

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

参数：

  • scene_ids （数组<String>，可选）：场景ID。提供时，查询会优先考虑场景ID。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_ids （数组<String>，可选）：设备相关场景的设备ID。

退货： 场景基本信息列表。

scene_run

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

参数：

  • scene_ids （数组<String>，必填）：要运行的场景ID。

退货： 场景执行结果。

scene_execution_history_inquiry

查询一个时间范围内的场景执行历史。

参数：

  • time_range （数组<String>，可选）：时间间隔。
  • scene_ids （数组<String>，可选）：场景ID。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_ids （数组<String>，可选）：设备ID。

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

自动化

automation_base_inquiry

查询自动化规则基础，可按自动化ID、位置ID或设备ID进行筛选。

参数：

  • automation_ids （数组<String>，可选）：自动化ID。提供时，查询会优先考虑自动化ID。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_ids （数组<String>，可选）：设备相关自动化的设备ID。

退货： 自动化规则列表。

automation_execution_history_inquiry

查询某个时间范围内的自动化执行历史记录。

参数：

  • time_range （数组<String>，可选）：时间间隔。
  • automation_ids （数组<String>，可选）：自动化ID。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_ids （数组<String>，可选）：设备ID。

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

能源消耗

energy_consumption_inquiry_for_position

按家庭/房间/空间查询用电量或成本，并提供汇总和详细视图。

参数：

  • data_type （字符串，必填）：查询类型--1 对于电力使用， 2 对于电力成本， 3 对于两者。
  • time_range （数组<String>，必填）：时间间隔。
  • time_gradient （字符串，可选）：粒度： 30min, 1hour, 1day, 1week, 1month.
  • data_aggregation_mode （字符串，可选）: total =汇总摘要， detail =详细视图。
  • positions （数组<String>，可选）：房间/空间ID。空时，查询所有有效房间。

退货： 按房间/空间统计的用电量/成本。

energy_consumption_inquiry_for_device

按设备查询用电量或成本，可按位置或设备过滤，并提供汇总和详细视图。

参数：

  • data_type （字符串，必填）: 1 =用电量， 2 =电费， 3 =两者都有。
  • time_range （数组<String>，必填）：时间间隔。
  • time_gradient （字符串，可选）: 30min, 1hour, 1day, 1week, 1month.
  • data_aggregation_mode （字符串，可选）: total =汇总摘要， detail =详细视图。
  • positions （数组<String>，可选）：房间/空间ID。
  • device_ids （数组<String>，可选）：设备ID。提供时，查询会优先考虑设备。

退货： 按设备统计的用电量/成本。

照明效果

lighting_effect_inquiry

查询家中可用的照明场景/效果。

参数： 无

退货： 带有名称和适用控制范围的效果列表。

device_lighting_effect_inquiry

查询每个设备支持的照明效果名称。

参数：

  • device_ids （数组<String>，必填）：用于查询效果的设备ID。

退货： 设备名称映射列表。

lighting_effect_control

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

参数：

  • effect_name （字符串，必填）：效果名称。
  • device_ids （数组<String>，可选）：目标设备ID。如果提供，控制会优先考虑设备。
  • position_ids （数组<String>，可选）：房间/空间ID。

退货： 灯光效果控制执行结果。

lighting_effect_config_params_inquiry

查询在灯光设备上配置照明效果所需的参数。

参数：

  • device_ids （数组<String>，必填）：目标照明设备ID。

退货： 效果配置参数，包括可配置项、值范围和保存的用户效果。

固件

device_firmware_inquiry

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

参数：

  • device_ids （数组<String>，可选）：设备ID。提供时，查询会优先考虑设备。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_types （数组<String>，可选）：设备类型。

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

device_firmware_upgrade

按设备、位置或类型筛选后，开始对符合条件的设备进行固件升级。

参数：

  • device_ids （数组<String>，可选）：设备ID。如果提供，请先升级这些设备。
  • position_ids （数组<String>，可选）：房间/空间ID。
  • device_types （数组<String>，可选）：设备类型。

退货： 固件升级提交结果。

参数约定

  • 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许可证。请参阅 许可证 文件以获取详细信息。

版权所有©2025 Aqara代理商。保留所有权利。

相关 MCP