SmartThings MCP 服务器

一个面向三星 SmartThings 的 MCP 服务器，通过 streamable-HTTP 暴露设备、场景、通知以及 规则（日常程序）的完整 CRUD 操作。

基于 FastMCP 构建。OAuth2 带自动令牌刷新——任何地方都不存在过期问题。

为什么

大多数 SmartThings MCP 服务器只能读取设备和触发场景。这个服务器还能创建、更新、删除和执行规则——日常程序背后的自动化引擎——而这正是让 LLM 构建家居自动化所真正需要的。

Related MCP server: SmartThingsMCP

⚠️ 规则与日常程序——提 bug 前请先阅读

| 事项 | 通过 API 可见？ | 可管理？ | | ------------------------------------------------- | ✅ | ✅ 完整 CRUD + 执行 | | 由 create_routine 创建的规则 | ✅ | ✅ 完整 CRUD + 执行 | | 通过 手机 App 创建的日常程序 | ❌ 永远不会 | ❌ 仅限 App |

如果你只在移动 App 里创建过日常程序，list_rules 返回 [] 是预期行为。这不是认证失败。这是三星官方记录的平台限制，任何客户端都无法绕过：

“你在 SmartThings App 中创建的自动规则（“rules”）是你可以通过规则 API 创建的规则的超集。在 App 中创建的日常程序不会出现在对 https://api.smartthings.com/v1/rules/ 发送的 GET 请求中。” — SmartThings 文档

工具

场景在设计上只读。 SmartThings 没有为场景提供写入权限范围（w:scenes 会被直接拒绝），因此场景只能被列出和执行，无法通过 API 创建。

列出和控制设备

构建自动化

这些示例中的设备名称、ID 和规则 ID 均为虚构。

设置

1. 创建一个带以下范围的 OAuth-In SmartApp：

   r:devices:* x:devices:* r:scenes:* x:scenes:* r:locations:*
   r:rules:* w:rules:* x:rules:*

2. 配置凭据：

   cp .env.example .env
   # fill in SMARTTHINGS_CLIENT_ID and SMARTTHINGS_CLIENT_SECRET

3. 授权一次以生成刷新令牌：

   python oauth_setup.py

   这会打开一个本地环回监听器（默认端口 9444）并写入 data/tokens.json。如果你的 SmartThings App 需要公共 HTTPS 回调，请在设置 OAUTH_REDIRECT_URI 的情况下使用 oauth_capture.py。

4. 运行它：

   docker compose up -d --build

   服务器监听于 http://localhost:8085/mcp。

客户端配置

{
  "mcpServers": {
    "smartthings": {
      "type": "http",
      "url": "http://localhost:8085/mcp"
    }
  }
}

该服务器是无状态的 streamable-HTTP：使用 Accept: application/json, text/event-stream 发送 JSON-RPC POST 请求。无需 mcp-session-id 头；响应以 SSE（event: message\ndata: ...）形式返回。

编写规则

rule_json 是一个 JSON 字符串，只包含 Rules API actions 数组——name 和 locationId 由工具添加。 Schema：https://developer.smartthings.com/docs/rules/rules-api

一个无害的规则，适合在验证 execute_routine 时使用：

[{"if": {"equals": {"left": {"integer": 1}, "right": {"integer": 1}},
  "then": [{"sleep": {"duration": {"value": {"integer": 1}, "unit": "Second"}}}]}}]

一个真实的规则——当一个开关打开时，关闭另一个：

[{"if": {"equals": {
    "left": {"device": {"devices": ["<deviceId>"], "component": "main",
             "capability": "switch", "attribute": "switch"}},
    "right": {"string": "on"}},
  "then": [{"command": {"devices": ["<otherDeviceId>"],
            "commands": [{"component": "main", "capability": "switch", "command": "off"}]}}]}}]

⚠️ execute_routine 会立即真实执行规则的操作。 它不会模拟。如果你的任何设备是你所关心机器的电源开关，请使用上面的 sleep 规则而不是 command 操作来进行验证。

认证

仅支持 OAuth2。data/tokens.json 必须包含 access_token、refresh_token 以及真实的未来时间戳 expires_at 这三个字段。后台保活循环（KEEPALIVE_HOURS，默认 12 小时）会主动刷新令牌，确保刷新令牌不会因闲置而过期。

有意不支持个人访问令牌（PAT）。 自 2024 年 12 月起，SmartThings PAT 在创建 24 小时后过期，无法用于长期运行的服务器。没有 PAT 回退机制，也没有 PAT 设置——每个请求（包括所有规则调用）都使用自动刷新的 OAuth 令牌。

故障排查

规则调用返回 401。 按顺序检查：

1. 确认 data/tokens.json 包含全部三个键且 expires_at 在未来。

2. 确认 locationId 已发送——当 locationId 缺失时，SmartThings 对 /rules 请求返回的是原始 HTML 格式的 401（而非 400），这会让一个简单的缺失参数 bug 看起来像认证失败。

3. 重启容器以强制刷新。

4. 最后手段：重新运行 oauth_setup.py。

端点怪癖（已处理——不要“修正”回去）：

• create: POST /rules?locationId=...

• execute: POST /rules/execute/{ruleId}?locationId=...（不是 /rules/{id}/execute）

容器报不健康。 MCP 端点只响应 POST，因此针对 / 的 HTTP 健康检查会返回 404。请使用 docker-compose.yml 中的 TCP 检查。

环境变量更改不生效。 执行 docker compose up -d --force-recreate——单纯的 docker restart 不会重新读取 .env。

许可证

MIT