星战科技xingzhan.cloud
返回市场
雅居乐-MCP服务器

雅居乐-MCP服务器

作者：aqara23 星标更新：2025-08-21
安装使用来源：spider==github.com

项目介绍

# 技术文档摘要

<div align="center" style="display: flex; align-items: center; justify-content: center; ">

  <img src="/readme/img/logo.png" alt="Aqara Logo" height="120">
  <h1>Aqara MCP 服务器</h1>

</div>

<div align="center">

English | [中文](/readme/README_CN.md) | [繁體中文](/readme/README_CHT.md) | [Français](/readme/README_FR.md) | [한국어](/readme/README_KR.md) | [Español](/readme/README_ES.md) | [日本語](/readme/README_JP.md) | [Deutsch](/readme/README_DE.md) | [Italiano](/readme/README_IT.md)

[![构建状态](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/aqara/aqara-mcp-server)
[![Go 版本](https://img.shields.io/badge/go-1.24+-blue.svg)](https://golang.org/dl/)
[![发布](https://img.shields.io/github/v/release/aqara/aqara-mcp-server)](https://github.com/aqara/aqara-mcp-server/releases)
[![许可证: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP 协议](https://img.shields.io/badge/MCP-Protocol-00ff00)](https://modelcontextprotocol.io/)

</div>

**Aqara MCP 服务器** 是基于 [模型上下文协议 (MCP)](https://modelcontextprotocol.io/introduction) 构建的智能家居自动化控制服务。该平台实现了 AI 助手（如 Claude、Cursor 等）与 Aqara 智能家居生态系统之间的无缝集成。

## 目录

- [目录](#目录)
- [特性](#特性)
- [工作原理](#工作原理)
- [快速开始](#快速开始)
  - [前提条件](#前提条件)
  - [步骤 1：账户认证](#步骤-1账户认证)
  - [步骤 2：如何使用](#步骤-2如何使用)
    - [选项 A：远程 MCP 服务器（推荐）](#选项-a远程-mcp-服务器推荐)
    - [选项 B：本地 MCP 服务器](#选项-b本地-mcp-服务器)
  - [步骤 3：验证](#步骤-3验证)
- [API 参考](#api参考)
  - [核心工具概述](#核心工具概述)
  - [设备控制 API](#设备控制-api)
    - [`device_control`](#device_control)
  - [设备查询 API](#设备查询-api)
    - [`device_query`](#device_query)
    - [`device_status_query`](#device_status_query)
    - [`device_log_query`](#device_log_query)
  - [场景管理 API](#场景管理-api)
    - [`get_scenes`](#get_scenes)
    - [`run_scenes`](#run_scenes)
  - [家庭管理 API](#家庭管理-api)
    - [`get_homes`](#get_homes)
    - [`switch_home`](#switch_home)
  - [自动化配置 API](#自动化配置-api)
    - [`automation_config`](#automation_config)
- [项目结构](#项目结构)
  - [目录结构](#目录结构)
  - [核心文件描述](#核心文件描述)
- [开发与贡献](#开发与贡献)
  - [开发环境设置](#开发环境设置)
  - [代码质量标准](#代码质量标准)
  - [贡献指南](#贡献指南)
- [许可证](#许可证)

## 特性

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

## 工作原理

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

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

快速开始

前提条件

  • 注册了智能设备的 Aqara 账户。
  • 支持 MCP 的 客户端（例如，Claude for Desktop，Cursor）。
  • Go 1.24+（仅在从源码部署到本地时需要）。

步骤 1：账户认证

无论部署模式如何，首先需要获取 Aqara 认证凭证：

  1. 访问登录页面： 🔗 https://cdn.aqara.com/app/mcpserver/login.html

  2. 完成登录过程：

    • 使用您的 Aqara 凭证登录。
    • 获取 api_key 和 base_url。

  3. 安全存储凭证：

    ⚠️ 请妥善保管您的 api_key 信息，不要泄露给他人。

    配置示例

步骤 2：如何使用

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

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

适用对象：希望快速启动而无需本地环境设置的用户。

优点：

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

配置 MCP 客户端：

  1. 打开设置：

    • 启动 Cursor。

    打开设置

  2. 添加服务器配置：

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

  3. 重启应用程序：

    • 重启 Cursor 以使更改生效。

选项 B：本地 MCP 服务器

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

优点：

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

安装步骤：

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

    推荐：下载预编译版本

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

    或者：从源码构建

    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

  2. 设置环境变量：

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

配置 MCP 客户端（例如，Claude for Desktop）：

  1. 打开设置：

    • 启动 Claude for Desktop。
    • 导航至：设置 → 开发者。

    Claude 打开设置

  2. 编辑配置文件：

    • 点击“编辑配置”。

    Claude 编辑配置

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

  4. 重启应用程序：

    • 重启 Claude for Desktop 以使更改生效。

步骤 3：验证

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

用户: "显示我家中的所有设备"
助手: [通过 MCP 查询设备列表]

用户: "打开客厅灯"
助手: [通过 MCP 执行设备控制]

用户: "运行傍晚场景"
助手: [通过 MCP 执行场景]

如果看到类似“🔧 已连接到 Aqara MCP 服务器”的消息，则配置成功！

API 参考

核心工具概述

工具类别工具描述
设备控制device_control直接设备操作
设备查询device_query, device_status_query, device_log_query综合设备信息
场景管理get_scenes, run_scenes自动化场景控制
家庭管理get_homes, switch_home多家庭环境支持
自动化automation_config定时任务配置

设备控制 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 为 "set" 时必需）。
    • 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 命令定义和程序入口点（包含主函数）
├── server.go             # 核心 MCP 服务器逻辑，工具定义及请求处理
├── smh.go                # Aqara 智能家居平台 API 接口封装层
├── middleware.go         # 中间件：用户认证、超时控制、异常恢复
├── config.go             # 全局配置管理和环境变量处理
├── go.mod                # Go 模块依赖管理文件
├── go.sum                # Go 模块依赖校验和文件
├── readme/               # README 文档和图像资源
│   ├── img/              # 图像资源目录
│   └── *.md              # 多语言 README 文件
├── LICENSE               # MIT 开源许可
└── README.md             # 主项目文档

核心文件描述

  • cmd.go: 基于 Cobra 框架实现的 CLI，定义了 run stdio 和 run http 启动模式以及主入口函数。
  • server.go: 核心 MCP 服务器实现，负责工具注册