Crestron Home MCP Server

创思宏（Crestron）家庭MCP服务器

一个用于控制Crestron家庭自动化系统的、可投入生产的模型上下文协议（MCP）服务器。该服务器使大型语言模型（LLMs）能够通过自然语言发现并控制Crestron设备，包括灯光、百叶窗、场景、恒温器、传感器等。

特点/特性

✨ 全面的设备控制

• 房间与设备全面发现房间及所有设备类型
• 遮光板/百叶窗位置控制（0-100%），批量操作
• 场景列出并激活预配置的场景
• 恒温器全面气候控制（温度、模式、风扇、定时）
• 传感器读取占用状态、光线、门以及电池状态
• 自然语言解析（或理解）对任意语言的设备名称进行模糊匹配

🛡️ 准生产就绪功能

• 会话管理10分钟会话处理的自动认证
• 错误处理包含可操作指导的全面错误信息
• 字符限制智能截断，配备实用的分页导航
• 批处理操作同时控制多个设备
• 多格式输出JSON和Markdown响应格式
• SSL 支持处理来自Crestron系统的自签名证书

🌍 多语言支持

• 意大利语：“关掉客厅的吊灯”
• “关掉客厅的吊灯”
• 任何语言：带有置信度评分的自然语言设备解析

要求

• Python 3.10 或更高版本
• 启用了REST API的Crestron家庭系统
• 通过网络访问Crestron Home系统
• 来自Crestron Home应用的授权令牌

安装

1. 克隆或下载

# Download the files
# - crestron_mcp.py
# - requirements.txt

2. 安装依赖项

pip install -r requirements.txt

3. 获取Crestron授权令牌

1. 打开 Crestron Home（克雷斯顿家居） 手机应用
2. 导航至： 安装程序设置 → 系统控制选项 → 网络API设置
3. 轻触 更新令牌
4. 复制生成的授权令牌
5. 安全地保存它——你将需要它进行身份验证

使用

运行MCP服务器

服务器默认使用stdio传输方式，这适合与MCP客户端进行集成：

python crestron_mcp.py

对于测试或调试，您可以设置超时时间来运行：

timeout 5s python crestron_mcp.py

与Claude桌面版的集成

在您的Claude Desktop MCP配置文件中添加：

macOS（发音：/ˈmækOS/，中文常译为“苹果电脑操作系统”或简称“苹果系统”）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "crestron": {
      "command": "python",
      "args": ["/path/to/crestron_mcp.py"]
    }
  }
}

可用工具

🔐 认证

crestron_authenticate

与Crestron Home系统建立会话。 在执行任何其他操作之前，必须首先调用此操作。

参数：

• host (字符串)：Crestron Home IP地址或主机名（例如，“192.168.1.100”）
• auth_token (字符串)：来自Crestron Home应用的授权令牌

示例：

{
  "host": "192.168.1.100",
  "auth_token": "your-token-here"
}

🏠 发现

crestron_list_rooms

将系统中所有房间的配置完成。

参数：

• response_format （可选）：“markdown”（默认）或“json”

crestron_list_devices

使用筛选选项发现所有设备。

参数：

• room_id （可选）：按房间ID筛选
• device_type （可选）：按类型过滤（照明、遮阳、恒温器、传感器等）
• response_format （可选）：“markdown”或“json”

🪟 遮阳控制

crestron_get_shades

获取当前遮阳装置的位置和状态。

参数：

• shade_id （可选）：特定色号ID
• response_format （可选）：“markdown”或“json”

crestron_set_shade_position

控制遮阳板位置（0 = 关闭，100 = 打开）。

参数：

• shades (array): 带有阴影效果的命令列表 id 并且 position (0-100)

示例：

{
  "shades": [
    {"id": 1, "position": 50},
    {"id": 2, "position": 100}
  ]
}

🎬 场景控制

crestron_list_scenes

列出所有可用场景并应用过滤器。

参数：

• room_id （可选）：按房间筛选
• scene_type （可选）：按类型过滤（照明、遮阳、媒体、气候等）
• response_format （可选）：“markdown”或“json”

crestron_activate_scene

通过ID激活一个场景。

参数：

• scene_id (整数)：要激活的场景ID

🌡️ 温控器控制

crestron_get_thermostats

获取恒温器的状态和功能。

参数：

• thermostat_id （可选）：特定的恒温器ID
• response_format （可选）：“markdown”或“json”

crestron_set_thermostat_setpoint

设定温度设定点。

参数：

• thermostat_id (整数)：恒温器ID
• setpoints (array): 一组设定点指令列表，其中 type (加热/冷却/自动) 和 temperature

示例：

{
  "thermostat_id": 15,
  "setpoints": [
    {"type": "Cool", "temperature": 72},
    {"type": "Heat", "temperature": 68}
  ]
}

crestron_set_thermostat_mode

设置系统模式（加热、制冷、自动、关闭）。

参数：

• thermostats (array): 包含恒温器命令的列表 id 和 mode

crestron_set_thermostat_fan

设置风扇模式（自动，开启）。

参数：

• thermostats (数组)：包含恒温器命令的列表，其中 id 并且 mode

📡 传感器

crestron_get_sensors

获取传感器读数（占用情况、光线水平、门状态、电池电量）。

参数：

• sensor_id （可选）：特定传感器ID
• sensor_subtype （可选）：按子类型过滤（占用传感器、光传感器、门传感器）
• response_format （可选）：“markdown”或“json”

🔍 设备分辨率

crestron_resolve_device

使用模糊匹配将自然语言描述解析为特定设备。

参数：

• utterance （字符串）：用任何语言描述的自然语言设备说明
• preferred_room_id （可选）：房间上下文，用于缩小搜索范围

示例：

{
  "utterance": "lampadario in soggiorno",
  "preferred_room_id": 1
}

返回值：

• 高置信度（≥0.8）：单一已解析设备
• 低置信度（\<0.8）：多个候选者需要澄清

工作流示例

示例1：意大利用户指令

用户“关掉客厅的吊灯”

工作流程：

1. 验证身份： crestron_authenticate 带有主机和令牌
2. 发现房间： crestron_list_rooms 查找“soggiorno”房间ID
3. 解决设备问题： crestron_resolve_device 说出“lampadario soggiorno”（客厅吊灯）
4. 获取设备详细信息使用返回的 device_id 与 crestron_list_devices
5. 控制装置将光亮度设置为0（具体实现取决于设备类型）

示例2：设置早晨场景

用户“激活早晨场景”

工作流程：

1. 认证： crestron_authenticate
2. 列出场景: crestron_list_scenes 寻找“早晨”场景
3. 激活： crestron_activate_scene 带有场景ID

示例3：气候控制

用户“将卧室恒温器设置为72度凉爽”

工作流程：

1. 验证身份： crestron_authenticate
2. 查找恒温器: crestron_get_thermostats 或者 crestron_resolve_device
3. 设定温度： crestron_set_thermostat_setpoint 冷却设定点为72
4. 设置模式: crestron_set_thermostat_mode to COOL（可译为“很酷”或“超赞”）

示例4：批量遮阳控制

用户“把客厅的所有百叶窗都关上”

工作流程：

1. 认证： crestron_authenticate
2. 找房间： crestron_list_rooms 获取客厅的ID
3. 寻找遮阳物： crestron_list_devices 按房间ID和类型“遮阳”进行过滤
4. 全部控制: crestron_set_shade_position 所有阴影ID均位于位置0

建筑学

会话管理

• 10分钟会话超时，带1分钟缓冲时间
• 在每次API调用前自动验证会话
• 当需要重新认证时，显示清晰的错误信息

错误处理

• 使用状态码进行全面的HTTP错误处理
• 可操作的错误信息引导用户找到解决方案
• 优雅地处理认证失败和超时情况

响应格式

Markdown 格式 （默认）：

• 带有标题和格式的可读性强的人类文本
• 针对用户展示进行了优化
• 包含有用的上下文和摘要

JSON 格式：

• 机器可读的结构化数据
• 为程序化处理提供完整的字段包含
• 所有工具间的一致架构

字符限制

• 25,000个字符的回复限制
• 智能截断，指标清晰
• 关于过滤和分页的有用指导

API 参考

Crestron Home REST API

基本URL： https://{host}/cws/api

认证:

• 头球 Crestron-RestAPI-AuthKey: {session_key}
• 会话持续时间：10分钟
• 所有系统均使用自签名的SSL证书

支持的端点:

• /login - 认证
• /rooms - 房间发现
• /devices - 设备发现
• /shades - 遮阳控制与状态
• /shades/SetState - 遮阳位置控制
• /scenes - 场景发现
• /scenes/recall/{id} - 场景激活
• /thermostats - 温控器状态
• /thermostats/SetPoint - 温度控制
• /thermostats/mode - 系统模式控制
• /thermostats/fanmode - 风扇控制
• /sensors - 传感器读数

故障排除

身份验证问题

问题“未认证或会话已过期” 解决方案打电话 crestron_authenticate 首先，需要有效的主机和令牌

问题“身份验证失败” 解决方案:

1. 验证主机IP/主机名是否正确且可达
2. 在Crestron Home应用中重新生成令牌
3. 确保在Crestron Home设置中已启用Web API
4. 检查网络连接

SSL证书警告

问题SSL验证警告 解决方案服务器会自动处理自签名证书。这是Crestron系统的预期行为。

未找到设备

问题“未找到ID为X的设备” 解决方案：

1. 使用 crestron_list_devices 查看所有可用设备
2. 验证设备ID是否正确
3. 检查设备是否已在线连接至 crestron_get_shades 或适当的状况检测工具

响应已截断

问题大响应被截断 解决方案：

1. 使用过滤参数（房间ID，设备类型）
2. 按ID请求特定设备
3. 在可用的地方使用分页功能
4. 选择JSON格式以获得更紧凑的输出

安全考虑因素

令牌存储

• 永远不要将授权令牌提交到版本控制系统中
• 安全存储令牌（使用环境变量、安全保险库）
• 在Crestron Home应用中定期轮换令牌

网络安全

• 在远程访问Crestron系统时，请使用VPN
• 如果条件允许，请在Crestron系统上实施IP白名单设置
• 监控API访问日志

会话安全

• 会话在10分钟后自动过期
• 每个会话都需要重新验证
• 监控未经授权的访问尝试

发展

代码结构

crestron_mcp.py
├── Constants & Configuration
├── Enums & Models (Pydantic)
├── Session Management
├── Helper Functions
│   ├── authenticate()
│   ├── api_request()
│   ├── format_markdown_list()
│   ├── truncate_response()
│   └── format_device_markdown()
├── Tools (MCP @mcp.tool decorated)
│   ├── Authentication
│   ├── Discovery
│   ├── Shade Control
│   ├── Scene Control
│   ├── Thermostat Control
│   ├── Sensor Monitoring
│   └── Device Resolution
└── Main Entry Point

测试

语法检查：

python -m py_compile crestron_mcp.py

进口核查:

python -c "import crestron_mcp"

运行服务器 （等待MCP客户端连接）：

python crestron_mcp.py

扩展服务器

要添加新的设备类型或功能：

1. 添加 Pydantic 模型定义输入验证模型
2. 创建工具功能使用 @mcp.tool 装饰器
3. 实现API逻辑使用辅助函数进行API调用
4. 添加错误处理提供清晰、可操作的错误信息
5. 格式化响应支持JSON和Markdown两种格式
6. 更新文档添加到此README文件中

演出

• 异步/等待所有输入/输出操作均为异步，以实现最佳性能
• 连接池单个HTTP客户端实例在请求间重复使用
• 会话缓存会话期间缓存身份验证密钥
• 批处理操作支持通过单个API调用控制多个设备

局限性

API限制

• Crestron Home REST API中不支持相机控制
• 灯光控制端点未明确记录（请使用设备发现功能）
• 门锁控制端点未明确记录
• 媒体室控制终端点未明确记录
• 不支持WebSocket/事件流（实时更新需轮询）

MCP服务器的限制

• 仅使用Stdio传输（未配置HTTP/SSE）
• 每个服务器实例单个并发会话
• 未实施速率限制（遵循Crestron系统限制）

贡献

这是一个遵循MCP最佳实践的、已准备好投入生产的实现方案。欢迎贡献以下方面的内容：

• 额外支持的设备类型（灯光、锁具、媒体室）
• 增强设备分辨率的算法
• 速率限制和请求排队
• WebSocket事件支持（如果添加到Crestron API中）
• 额外的传输选项（HTTP、SSE）

许可证

\[您的许可证在此\]

支持

对于以下相关问题：

• MCP 服务器审查错误信息和日志
• Crestron API请查阅Crestron Home REST API文档
• 设备控制使用发现工具验证设备ID和功能
• 认证检查令牌有效性及网络连接状态

致谢

构建于：

• MCP Python SDK - FastMCP框架
• httpx（注：httpx通常是一个用于执行HTTP请求的工具或库的名称，直接翻译为“httpx”即可，因为这是一个专有名词，在中文中通常不进行翻译。） - 异步HTTP客户端
• Pydantic（发音类似“派当尼克”） - 数据验证

根据Crestron Home REST API规范以及MCP构建高质量LLM集成的最佳实践。