Smart Home Device Control

Control smart home devices and query information by connecting large models to smart home backend APIs.

GitHub

智能家居设备控制 MCP 服务器

这个 MCP 服务器允许大模型通过 Model Context Protocol (MCP) 协议访问智能家居后端 API，实现设备控制和信息查询功能。

功能特点

  • 提供设备控制接口，支持各种智能家居设备的操作
  • 查询设备概览和详细信息
  • 内置丰富的设备文档，指导大模型正确使用各类设备
  • 支持通过命令行参数配置后端 API 地址和认证令牌

支持的设备类型及控制参数

  1. 空调 (air_conditioner):

    • 设置温度 (set_temperature)
      • 参数: temperature (范围: 16-30°C)
      • 示例: control_device(device_id="5", action="set_temperature", parameters={"temperature": 24})
    • 开关控制 (switch)
      • 参数: state ("on"或"off")
      • 示例: control_device(device_id="5", action="switch", parameters={"state": "on"})

  2. 冰箱 (refrigerator):

    • 设置温度 (set_temperature)
      • 参数: temperature (范围: -20到10°C)
      • 示例: control_device(device_id="8", action="set_temperature", parameters={"temperature": 4})
    • 开关控制 (switch)
      • 参数: state ("on"或"off")
      • 示例: control_device(device_id="8", action="switch", parameters={"state": "on"})

  3. 灯 (light):

    • 设置亮度 (set_brightness)
      • 参数: brightness (范围: 0-100)
      • 示例: control_device(device_id="12", action="set_brightness", parameters={"brightness": 80})
    • 开关控制 (switch)
      • 参数: state ("on"或"off")
      • 示例: control_device(device_id="12", action="switch", parameters={"state": "on"})

  4. 门锁 (lock):

    • 设置锁状态 (set_lock)
      • 参数: state ("lock"或"unlock")
      • 示例: control_device(device_id="15", action="set_lock", parameters={"state": "lock"})

  5. 摄像头 (camera):

    • 控制录制 (set_recording)
      • 参数: state ("start"或"stop")
      • 示例: control_device(device_id="20", action="set_recording", parameters={"state": "start"})
    • 设置分辨率 (set_resolution)
      • 参数: resolution ("720p", "1080p"或"4k")
      • 示例: control_device(device_id="20", action="set_resolution", parameters={"resolution": "1080p"})

设备状态说明

  • online: 设备在线正常工作
  • offline: 设备离线
  • error: 设备出现错误

使用方法

启动服务器

可以通过 python 环境运行脚本：

pip install fastmcp requests

python mcp_server.py --backend http://backend-api-address:8000/api/v1 --token <your_auth_token>

也可以从 Release 中下载对应平台的二进制可执行文件，直接运行：

mcp_server --backend http://backend-api-address:8000/api/v1 --token <your_auth_token>

your_auth_token 令牌需要在通过POST /auth/login登录到后端后获取

参数说明:

  • --backend: 后端 API 地址，默认为 http://localhost:8000
  • --token: 认证令牌，用于访问后端 API 的授权

对话测试

你可以使用 cursor 或者 cline(VSCode插件)与大模型对话，在其中调用MCP服务器。

{
  "mcpServers": {
    "cpm-smarthome": {
      "disabled": false,
      "timeout": 60,
      "transportType": "stdio",
      "command": "python",
      "args": [
        "/path/to/mcp_server.py",
        "--token",
        "your_auth_token",
        "--backend",
        "http://backend-api-address:8000/api/v1"
      ]
    }
  }
}

可用工具

服务器提供以下工具供大模型使用:

  1. get_config(): 获取当前配置信息

    • 返回后端 API 地址和认证令牌配置状态
    • 注意：认证令牌不会返回明文

  2. get_device_overview(): 获取所有设备的概览信息

    • 返回系统中所有设备的基本信息列表
    • 包括设备ID、名称、状态等信息

  3. get_device_detail(device_id): 获取特定设备的详细信息

    • 返回指定设备的详细状态信息
    • 包括设备状态、功耗、运行时间、日志等

  4. control_device(device_id, action, parameters): 控制特定设备执行操作

    • 用于向指定设备发送控制命令
    • 具体参数请参考上方设备类型说明

  5. get_device_type_docs(device_type): 获取设备类型的控制文档

    • 不指定设备类型时返回所有设备类型的概览
    • 指定设备类型时返回该类型的详细控制文档

后端 API 接口

本服务器连接到以下后端 API 接口:

  1. 控制设备: POST /devices/{device_id}/control/
  2. 查询设备概要: GET /devices/overview/
  3. 查询设备详情: GET /devices/{device_id}/detail/

注意事项

  • 在使用任何工具前，请确保服务器启动时已提供正确的认证令牌
  • 不同类型的设备支持不同的操作和参数，请参考设备文档了解详情
  • 所有API调用都需要提供有效的认证令牌
  • 设备控制操作会返回操作结果，请检查返回的 success 字段确认操作是否成功

Related Servers