SmartThings MCP Server

SmartThings MCP服务器（Python）

一种生产就绪的、Docker化的MCP（模型上下文协议）服务器，用于通过个人访问令牌（PAT）控制和查询SmartThings设备。

特性

• ✅ 完全异步：通过适当的资源管理实现高效的异步/等待
• ✅ 综合录井：调试和监控的详细日志记录
• ✅ 类型安全：完整的类型提示和Pydantic验证
• ✅ 错误处理：使用有意义的消息进行结构化错误处理
• ✅ 优化的API调用：直接查找设备以最小化API请求
• ✅ Docker最佳实践：非root用户、健康检查、最小图像大小
• ✅ 资源清理：正确的HTTP客户端生命周期管理

项目结构

.
├── Dockerfile              # Production-ready Docker image
├── docker-compose.yml      # Docker Compose configuration
├── .dockerignore          # Docker build exclusions
├── .env.example           # Environment variable template
├── requirements.txt       # Python dependencies
├── app/
│   ├── __init__.py
│   ├── main.py           # MCP server and tool definitions
│   └── smartthings.py    # SmartThings API client
└── README.md             # This file

设置

1.获取SmartThings个人访问令牌（PAT）

1. 访问https://account.smartthings.com/tokens
2. 点击“生成新令牌”
3. 为其命名（例如，“MCP服务器”）
4. 选择所需范围：

- devices （阅读并执行） - locations （阅读）

1. 复制生成的令牌

2.配置环境

cp .env.example .env
# Edit .env and add your SMARTTHINGS_PAT

3.构建和运行

使用Docker

# Build the image
docker build -t smartthings_mcp:latest .

# Run with stdio transport
docker run --rm -i \
  -e SMARTTHINGS_PAT=$SMARTTHINGS_PAT \
  -e SMARTTHINGS_LOCATION_ID=$SMARTTHINGS_LOCATION_ID \
  smartthings_mcp:latest

使用Docker Compose

# Build and run
docker compose build
docker compose run --rm smartthings-mcp python -m app.main

本地开发

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export SMARTTHINGS_PAT="your_pat_here"

# Run the server
python -m app.main

可用工具

list_locations()

列出当前PAT可访问的所有SmartThings位置。

退货：位置对象列表 locationId, name，以及元数据。

______________________________________________________________________

list_rooms(locationId?)

列出SmartThings位置的所有房间。

参数:

• locationId （可选）：位置ID。回退到 SMARTTHINGS_LOCATION_ID env-var或第一个可用位置。

退货：房间对象列表 roomId, name，以及元数据。

______________________________________________________________________

list_devices(locationId?, roomId?)

列出所有SmartThings设备，可选择按位置和/或房间过滤。

参数:

• locationId （可选）：按位置过滤设备
• roomId （可选）：按房间过滤设备

退货：设备对象列表 deviceId, label, capabilities，以及元数据。

______________________________________________________________________

device_status({ deviceId?, name? })

获取SmartThings设备的当前状态。

参数:

• deviceId （可选）：唯一设备ID（效率优先）
• name （可选）：要搜索的设备名称/标签（速度较慢，搜索所有设备）

退货：具有当前状态和扁平化摘要的设备信息。

备注：至少提供以下之一 deviceId 或 name.

______________________________________________________________________

switch_device({ deviceId?, name?, command, component? })

打开或关闭SmartThings开关设备。

参数:

• deviceId （可选）：唯一设备ID（首选）
• name （可选）：要搜索的设备名称/标签
• command （必填）：要么 "on" 或 "off"
• component （可选）：设备组件（默认值： "main")

退货：设备信息和命令执行结果。

______________________________________________________________________

fridge_status({ deviceId?, name? })

获取SmartThings冰箱/冰箱设备的详细状态。

参数:

• deviceId （可选）：唯一设备ID
• name （可选）：要搜索的设备名称/标签

退货：冰箱特定状态摘要，包括：

• 电源状态
• 冰箱和冷冻柜温度
• 门打开/关闭状态
• 制冰机状态
• 霜方式
• 所有温度、门、冰、湿度和能源相关属性

备注：如果两个参数都没有提供，则会自动搜索名称中包含“冰箱”或“冰箱”的设备。

______________________________________________________________________

device_health(deviceId)

获取SmartThings设备的运行状况。

参数:

• deviceId （必填）：唯一设备ID

退货：设备健康信息，包括在线/离线状态。

架构改进

异步设计

• 所有工具都是完全异步的，以提高并发性
• 使用具有连接池的单个HTTP客户端
• 通过寿命处理器在关机时进行适当的清理

错误处理

• 所有输入的Pydantic验证
• 结构化错误消息
• 巧妙的回退（例如，健康检查返回“未知”而不是失败）

性能优化

• 使用时直接设备GET端点 deviceId （避免列出所有设备）
• 高效的设备搜索，提前退出
• 跨所有请求的连接重用

安全

• 在Docker中以非root用户身份运行
• 最小攻击面（无暴露端口）
• 令牌从未记录

日志记录

• INFO和DEBUG级别的全面日志记录
• 带时间戳的结构化日志格式
• 用于调试的请求/响应日志记录

环境变量

发展

运行测试

# Install dev dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest

日志记录级别

通过环境设置日志级别：

# Debug level (verbose)
export LOG_LEVEL=DEBUG

# Info level (default)
export LOG_LEVEL=INFO

# Warning level (quiet)
export LOG_LEVEL=WARNING

代码风格

该项目如下：

• PEP 8风格指南
• 为所有函数键入提示
• 所有公共API的文档字符串

故障排除

“SMARTTHINGS_PAT是必需的”

• 确保您已设置 SMARTTHINGS_PAT 环境变量
• 检查您的PAT是否具有正确的范围

“未找到位置”

• 验证您的PAT是否 locations:read 范围
• 检查SmartThings帐户中是否至少有一个位置

“找不到设备”

• 使用 list_devices() 查看可用设备
• 确保设备名称或ID正确（名称不区分大小写）
• 如果应用了过滤器，请检查设备是否在指定的位置/房间

HTTP超时错误

• 增加超时时间 smartthings.py （默认值：15秒）
• 检查SmartThings API的网络连接

许可证

MIT许可证-可根据需要自由使用和修改。

贡献

欢迎投稿！拜托：

1. 为新功能添加测试
2. 更新文档
3. 遵循现有代码样式
4. 确保所有测试通过

更新日志

v2.0.0（当前）

• ✅ 完全异步/等待实现
• ✅ 全面的日志记录和错误处理
• ✅ 通过直接设备查找优化API调用
• ✅ Docker最佳实践（非root用户、健康检查）
• ✅ 所有输入的Pydantic验证
• ✅ 适当的资源清理
• ✅ 完整的类型提示和文档字符串

v1.0.0（原始）

• 基本MCP服务器实现
• 同步工具功能
• 基本错误处理