SmartThings MCP Server

Samsung SmartThings용 MCP 서버로, streamable-HTTP를 통해 기기, 장면, 알림 및 Rules (Routines)에 대한 전체 CRUD를 노출합니다.

FastMCP로 구축되었습니다. 자동 토큰 갱신이 포함된 OAuth2 — 어디에도 만료되는 Personal Access Token이 없습니다.

왜

대부분의 SmartThings MCP 서버는 기기 읽기와 장면 실행만 지원합니다. 이 서버는 여기에 더해 Rules — Routines의 기반이 되는 자동화 엔진 — 를 생성, 업데이트, 삭제, 실행할 수 있습니다. 이것이야말로 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 및 rule 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 앱에서 공개 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을 검증할 때 안전하게 사용할 수 있는 무해한 rule:

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

실제 rule — 한 스위치가 켜지면 다른 스위치를 끄는 예:

[{"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은 rule의 작업을 실제로 즉시 실행합니다. 시뮬레이션하지 않습니다. 중요한 기계의 전원 스위치인 기기가 있다면 command 작업 대신 위의 sleep rule로 검증하세요.

인증 참고 사항

OAuth2 만 지원합니다. data/tokens.json에는 access_token, refresh_token, 그리고 실제 미래 시각의 expires_at 세 가지가 모두 포함되어야 합니다. 백그라운드 keep-alive 루프(KEEPALIVE_HOURS, 기본 12시간)가 사전에 갱신하므로 리프레시 토큰이 사용되지 않아 만료되는 일이 없습니다.

Personal Access Token은 의도적으로 지원하지 않습니다. 2024년 12월부터 SmartThings PAT는 생성 후 24시간이 지나면 만료되므로 장기 실행 서버에는 사용할 수 없습니다. PAT 폴백도 PAT 설정도 없습니다. 모든 Rules 호출을 포함한 모든 요청은 자동 갱신되는 OAuth 토큰을 사용합니다.

문제 해결

rules 호출 시 401. 순서대로:

1. data/tokens.json에 세 키가 모두 있고 expires_at이 미래 시각인지 확인하세요.

2. locationId가 전송되고 있는지 확인하세요 — SmartThings는 /rules 요청에 locationId가 없으면 400이 아닌 순수 HTML 401을 반환합니다. 그래서 단순한 누락 파라미터 버그가 인증 실패처럼 보입니다.

3. 컨테이너를 재시작하여 강제로 갱신하세요.

4. 최후의 수단: oauth_setup.py를 다시 실행하세요.

엔드포인트 특이 사항 (이미 처리되어 있음 — 다시 "수정"하지 마세요):

• 생성: POST /rules?locationId=...

• 실행: POST /rules/execute/{ruleId}?locationId=... (아님 /rules/{id}/execute)

컨테이너가 unhealthy로 보고됩니다. MCP 엔드포인트는 POST만 응답하므로 /에 대한 HTTP healthcheck는 404를 반환합니다. docker-compose.yml의 TCP check를 사용하세요.

환경 변수 변경 사항이 적용되지 않습니다. docker compose up -d --force-recreate — 단순 docker restart는 .env를 다시 읽지 않습니다.

라이선스

MIT