Smart Home Device Control

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

View on 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