SmartThings MCP

Servidor do Protocolo de Contexto de Modelo do Samsung SmartThings

Documentação

Servidor SmartThings MCP da Lango

Um servidor Model Context Protocol (MCP) que expõe a SmartThings Public API da Samsung como ferramentas, recursos e eventos em tempo real amigáveis para LLMs.

Recursos

Carregamento Preguiçoso: Ferramentas são descobríveis sem autenticação - só valida chaves de API quando as ferramentas são invocadas
Encapsula operações comuns do SmartThings como Ferramentas MCP
- Dispositivos: list_devices, get_device, get_device_status, list_device_capabilities, send_device_command
- Locais e Cômodos: list_locations, list_rooms, create_room, delete_room
- Cenas e Regras: list_scenes, execute_scene, list_rules
- Hubs: list_hubs, get_hub_health
- Assinaturas: list_subscriptions, create_subscription, delete_subscription
- Agendamentos: list_schedules, create_schedule, delete_schedule
- Histórico: get_device_history
- Capacidades: get_capability
Expõe dados de dispositivo / status / local como Recursos MCP com cache de leitura
Suporta todos os transportes oficiais do MCP-Go
- Stdio (CLI / local), StreamableHTTP, Server-Sent Events (SSE)
Poller periódico publica status ao vivo dos dispositivos para clientes SSE
Zero dependências externas além do logger mcp-go e zap

Requisitos

Go ≥ 1.23
Um PAT (Personal Access Token) válido do SmartThings

Obtendo um Personal Access Token (PAT)

Acesse SmartThings Personal Access Tokens.
Faça login com sua conta Samsung.
Clique em Generate new token.
Insira um nome para seu token e selecione os escopos autorizados (ex.: devices, locations, scenes, rules, schedules).
Clique em Generate token.
Copie e salve o token imediatamente (ele não será exibido novamente).

Variáveis de Ambiente

Nome	Padrão	Descrição
`smartThingsToken`, `SMARTTHINGS_TOKEN`	–	Token Bearer para a API do SmartThings. Obrigatório para operações SmartThings, mas o servidor iniciará sem ele para descoberta de ferramentas
`stBaseUrl`, `ST_BASE_URL`	`https://api.smartthings.com`	Substituição para testes / servidores mock
`MCP_LOG_LEVEL`	`info`	`debug`

Instalação

Instalando via Smithery

Para instalar o smartthings-mcp para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @langowarny/smartthings-mcp --client claude

Instalação Manual

git clone https://github.com/langowarny/smartthings-mcp.git
cd smartthings-mcp
go mod download

Execução

Stdio

SMARTTHINGS_TOKEN=123ab456-xxx... go run ./cmd/server -transport stdio

StreamableHTTP

SMARTTHINGS_TOKEN=123ab456-xxx... \
  go run ./cmd/server -transport stream -host 0.0.0.0 -port 8081

Requisição de teste:

curl -X POST http://localhost:8081/mcp/tools/call \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_devices"}}'

SSE

SMARTTHINGS_TOKEN=123ab456-xxx... \
  go run ./cmd/server -transport sse -host 0.0.0.0 -port 8081

# Open event stream
echo -e 'GET /mcp/sse HTTP/1.1\nHost: localhost:8081\n\n' | nc localhost 8081

O servidor emite notificações smartthings/device_status a cada 30 segundos.

Catálogo de Ferramentas

Ferramenta	Parâmetros	Descrição
`list_devices`	`location_id?`	Listar dispositivos do usuário
`get_device`	`device_id`	Metadados do dispositivo
`get_device_status`	`device_id`	Status ao vivo
`list_device_capabilities`	`device_id`	Capacidades suportadas
`send_device_command`	`device_id`, `component`, `capability`, `command`, `arguments?[]`	Enviar comando
`list_locations`	–	Listar locais
`list_rooms`	`location_id`	Listar cômodos em um local
`create_room`	`location_id`, `name`	Criar um novo cômodo
`delete_room`	`location_id`, `room_id`	Excluir um cômodo
`list_scenes`	–	Listar todas as cenas
`execute_scene`	`scene_id`	Acionar cena
`list_rules`	–	Listar regras de automação
`list_hubs`	–	Listar hubs
`get_hub_health`	`hub_id`	Obter status de saúde do hub
`list_subscriptions`	`installed_app_id`	Listar assinaturas
`create_subscription`	`installed_app_id`, `device_id`, ...	Assinar eventos de dispositivos
`delete_subscription`	`installed_app_id`, `subscription_id`	Excluir assinatura
`list_schedules`	`installed_app_id`	Listar agendamentos
`create_schedule`	`installed_app_id`, `name`, `cron`	Criar agendamento cron
`delete_schedule`	`installed_app_id`, `schedule_id`	Excluir agendamento
`get_device_history`	`device_id`	Obter eventos recentes do dispositivo
`get_capability`	`capability_id`, `version`	Obter definição de capacidade

Padrões de Recursos

Modelo de URI	Descrição	MIME
`st://devices/{device_id}`	Metadados do dispositivo	`application/json`
`st://devices/{device_id}/status`	Status ao vivo	`application/json`
`st://locations/{location_id}`	Metadados do local	`application/json`

Desenvolvimento

go vet ./...
go test ./...
go run ./cmd/server -transport stream

Os logs são emitidos via Uber Zap; ajuste MCP_LOG_LEVEL para verbosidade.