MCP 服务器

Smart Home Device Control MCP Server

Enables AI models to control and query smart home devices (air conditioners, lights, locks, cameras, refrigerators) through a backend API. Supports device control operations, status queries, and detailed device information retrieval with built-in documentation for proper device usage.

README

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

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

功能特点

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

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

空调 (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"})
冰箱 (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"})
灯 (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"})
门锁 (lock):
- 设置锁状态 (set_lock)
  - 参数: state ("lock"或"unlock")
  - 示例: control_device(device_id="15", action="set_lock", parameters={"state": "lock"})
摄像头 (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"
      ]
    }
  }
}

可用工具

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

get_config(): 获取当前配置信息
- 返回后端 API 地址和认证令牌配置状态
- 注意：认证令牌不会返回明文
get_device_overview(): 获取所有设备的概览信息
- 返回系统中所有设备的基本信息列表
- 包括设备ID、名称、状态等信息
get_device_detail(device_id): 获取特定设备的详细信息
- 返回指定设备的详细状态信息
- 包括设备状态、功耗、运行时间、日志等
control_device(device_id, action, parameters): 控制特定设备执行操作
- 用于向指定设备发送控制命令
- 具体参数请参考上方设备类型说明
get_device_type_docs(device_type): 获取设备类型的控制文档
- 不指定设备类型时返回所有设备类型的概览
- 指定设备类型时返回该类型的详细控制文档