SmartThings MCP Server

Samsung SmartThings 向けの MCP サーバーで、streamable-HTTP 経由でデバイス、シーン、通知、そして Rules（Routines）の完全な CRUD を公開します。

FastMCP で構築されています。OAuth2 による自動トークン更新に対応しており、期限切れになる Personal Access Token はどこにもありません。

なぜ必要か

ほとんどの SmartThings MCP サーバーは、デバイスの読み取りとシーンの実行しかできません。このサーバーはさらに、Routines の背後にある自動化エンジンである Rules の作成・更新・削除・実行も行います。LLM にホームオートメーションを構築させるために実際に必要なのは、こちらです。

Related MCP server: SmartThingsMCP

⚠️ Rules vs Routines — バグを報告する前にお読みください

Routines をモバイルアプリでしか作成したことがない場合、list_rules が [] を返すのは想定どおりです。認証の失敗ではありません。これは Samsung プラットフォームの文書化された制限であり、どのクライアントも回避できません:

"SmartThings アプリで作成する自動ルーチン（"rules"）は、Rules API で作成できるもののスーパーセットです。アプリで作成した Routines は、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. 1 回だけ認証して refresh token を発行します:

   python oauth_setup.py

   これにより、ローカルのループバックリスナー（デフォルトポート 9444）が起動し、data/tokens.json に書き込まれます。SmartThings アプリが代わりにパブリックな 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: {...}）として返されます。

Rules の書き方

rule_json は、Rules API の actions 配列のみを含む JSON 文字列です。name と locationId はツール側で追加されます。 スキーマ: 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 はルールのアクションを実際に、即座に実行します。 シミュレーションではありません。対象のデバイスの中に、大切な機械の電源スイッチがある場合は、command アクションではなく、上記の sleep ルールで検証してください。

認証に関する注意

OAuth2 のみです。data/tokens.json には、access_token、refresh_token、そして実際に未来の時刻を示す expires_at の 3 つすべてが含まれている必要があります。バックグラウンドのキープアライブループ（KEEPALIVE_HOURS、デフォルト 12 時間）が事前に更新するため、refresh token が未使用のまま失効することはありません。

Personal Access Token は意図的にサポートされていません。 2024 年 12 月以降、SmartThings の PAT は作成から 24 時間で有効期限が切れるため、長時間稼働するサーバーでは使用できません。PAT のフォールバックも PAT 設定もありません。すべてのリクエスト（Rules 呼び出しを含む）は、自動更新される OAuth トークンを使用します。

トラブルシューティング

Rules 呼び出しで 401 が返る場合。 次の順に確認してください:

1. data/tokens.json に 3 つのキーすべてと未来の expires_at があることを確認します。

2. locationId が送信されていることを確認します — /rules リクエストに locationId がない場合、SmartThings は 400 ではなく素の HTML の 401 を返すため、単純なパラメータ不足のバグが認証失敗のように見えます。

3. コンテナを再起動して強制的に更新します。

4. 最終手段: oauth_setup.py を再実行します。

エンドポイントの癖（すでに対応済み — 勝手に「修正」しないでください）:

• 作成: POST /rules?locationId=...

• 実行: POST /rules/execute/{ruleId}?locationId=...（/rules/{id}/execute ではない）

コンテナが unhealthy と報告される場合。 MCP エンドポイントは POST にのみ応答するため、/ に対する HTTP ヘルスチェックは 404 を返します。docker-compose.yml の TCP チェックを使用してください。

環境変数の変更が反映されない場合。 docker compose up -d --force-recreate を実行してください — 通常の docker restart では .env は再読み込みされません。

ライセンス

MIT