SwitchBot

Controle dispositivos inteligentes SwitchBot através de sua API oficial, permitindo automação e integração com assistentes de IA.

GitHub
7
Experimente este MCPPatrocinado

Documentação

@genm-dev/switchbot-mcp

Servidor MCP SwitchBot v3 para assistentes de IA.

License CI CodeQL

日本語

Status do projeto

O repositório de código-fonte é público, mas a v3 ainda não foi publicada no npm nem no Registro MCP oficial. Os comandos npm, npx e de um clique neste README só se tornam utilizáveis após o primeiro lançamento acompanhado em Issue #7. Compile a partir do código-fonte para avaliação atual.

Esta é uma integração comunitária não oficial e não é afiliada nem endossada pela SwitchBot. Chamadas de ferramentas podem controlar dispositivos físicos e executar cenas. Revise as ações solicitadas, o acesso a credenciais e a exposição de rede antes do uso; não trate a confirmação de um cliente de IA como uma fronteira de autorização.

Compilar a partir do código-fonte (disponível agora)

git clone https://github.com/genm/switchbot-mcp.git
cd switchbot-mcp
npm ci --ignore-scripts
npm run build

Execute node build/index.js com a configuração obrigatória abaixo. O processo falha de forma segura quando as credenciais estão ausentes.

Instalação do pacote (após o primeiro lançamento)

Instalação com um clique

Install in Cursor Install in VS Code

Estes links atualmente apontam para o pacote npm público planejado. Após a publicação, substitua SWITCHBOT_TOKEN e SWITCHBOT_SECRET pelas suas credenciais e revise a configuração antes de iniciar o servidor.

VS Code

code --add-mcp '{"name":"switchbot","command":"npx","args":["-y","@genm-dev/switchbot-mcp"],"env":{"SWITCHBOT_TOKEN":"YOUR_SWITCHBOT_TOKEN","SWITCHBOT_SECRET":"YOUR_SWITCHBOT_SECRET","MCP_TRANSPORT":"stdio"}}'

Claude Desktop

{
  "mcpServers": {
    "switchbot": {
      "command": "npx",
      "args": ["-y", "@genm-dev/switchbot-mcp"],
      "env": {
        "SWITCHBOT_TOKEN": "YOUR_SWITCHBOT_TOKEN",
        "SWITCHBOT_SECRET": "YOUR_SWITCHBOT_SECRET",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Destaques

  • v3.0.0 na plataforma Node.js 24 LTS
  • MCP SDK v2 com cobertura explícita de negociação do protocolo MCP 2026-07-28
  • fetch nativo com validação rigorosa de respostas upstream
  • Arquitetura em camadas (cliente SwitchBot / ferramentas MCP / transportes)
  • Transportes stdio e Streamable HTTP
  • Chave de API necessária para transporte HTTP
  • Validação de Origin e Host do mesmo host para implantações HTTP
  • Saídas estruturadas de ferramentas MCP (structuredContent)
  • Anotações de risco MCP e novas tentativas limitadas para solicitações SwitchBot somente leitura
  • Logs operacionais JSONL com dados sensíveis mascarados
  • CI em repositório público em runtimes, artefatos de pacote e contêineres suportados

Requisitos

  • Node.js 24.15+
  • Token e segredo da API aberta SwitchBot

Instalação

Disponível após o primeiro lançamento:

npm install @genm-dev/switchbot-mcp

Configuração

Obrigatório

  • SWITCHBOT_TOKEN
  • SWITCHBOT_SECRET

Transporte

  • MCP_TRANSPORT=stdio|http (padrão: stdio)
  • MCP_SERVER_API_KEY (obrigatório para http; use um segredo de alta entropia sem espaços em branco ao redor)
  • MCP_HTTP_HOST (padrão: 127.0.0.1)
  • MCP_HTTP_ALLOWED_HOSTS (nomes de host de proxy/públicos opcionais separados por vírgula)
  • MCP_HTTP_PORT (padrão: 8787)
  • MCP_HTTP_PATH (padrão: /mcp)

Solicitações HTTP com um cabeçalho Origin devem usar um nome de host da mesma lista de permissões que o cabeçalho Host. Localhost e o host de vinculação configurado são incluídos automaticamente. Adicione nomes de host de proxy reverso explicitamente; solicitações malformadas ou de origem cruzada são rejeitadas.

Tempo de execução

  • SWITCHBOT_TIMEOUT_MS (padrão: 10000)
  • SWITCHBOT_LIST_CACHE_TTL_MS (padrão: 30000)
  • LOG_LEVEL=debug|info|warn|error (padrão: info)

Somente teste (opcional)

  • SWITCHBOT_BASE_URL (substitui o endpoint da API SwitchBot para testes e2e determinísticos)

A substituição é aceita somente quando NODE_ENV=test e a URL usa localhost, 127.0.0.0/8 ou [::1]. Isso impede que credenciais de produção sejam redirecionadas para outra origem.

Ferramentas MCP (v3)

  1. switchbot_list_devices
  2. switchbot_get_device_status
  3. switchbot_set_power
  4. switchbot_send_command
  5. switchbot_list_scenes
  6. switchbot_execute_scene
  7. switchbot_list_devices_raw (avançado, campos upstream brutos)

Consulte os detalhes de migração: docs/migration-v2-to-v3.md

Uso

stdio (pacote / npx, após o primeiro lançamento)

{
  "mcpServers": {
    "switchbot": {
      "command": "npx",
      "args": ["-y", "@genm-dev/switchbot-mcp"],
      "env": {
        "SWITCHBOT_TOKEN": "...",
        "SWITCHBOT_SECRET": "...",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

stdio (build de desenvolvimento local)

{
  "mcpServers": {
    "switchbot": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "SWITCHBOT_TOKEN": "...",
        "SWITCHBOT_SECRET": "...",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP (Streamable HTTP)

MCP_TRANSPORT=http \
MCP_SERVER_API_KEY=your_api_key \
SWITCHBOT_TOKEN=... \
SWITCHBOT_SECRET=... \
npx -y @genm-dev/switchbot-mcp

Endpoint: http://127.0.0.1:8787/mcp

Gere a credencial de portador com um gerador criptograficamente seguro, por exemplo openssl rand -hex 32, e injete-a a partir do seu gerenciador de segredos. O servidor Node fala HTTP simples. Para qualquer implantação fora de loopback, encerre TLS em um proxy reverso confiável, restrinja o acesso à rede e configure seu nome de host em MCP_HTTP_ALLOWED_HOSTS; não exponha o listener Node diretamente à internet pública.

Integração opcional de terceiros: Smithery

Smithery não é um canal de distribuição oficial para este projeto. npm, o Registro MCP oficial e as configurações diretas de cliente acima são os caminhos canônicos de instalação e descoberta.

A configuração Smithery mantida usa seu formato de repositório legado e não foi revalidada contra o modelo de publicação MCPB/URL atual da Smithery. O comando abaixo é informativo e não deve ser anunciado como suportado até ser verificado separadamente após o primeiro lançamento.

npx -y @smithery/cli@latest install @genm-dev/switchbot-mcp --client claude

Estratégia de testes

Portões obrigatórios (determinísticos)

npm run check
npm run test:coverage

npm run check inclui verificação de tipos, linting, formatação, testes de protocolo e transporte MCP, build, validação de metadados de pacote, instalação/execução do artefato empacotado e um SBOM validado de dependências de produção. npm run test:coverage aplica limites de cobertura.

Ao alterar o runtime Docker, execute também:

npm run smoke:container

Isso verifica falha de configuração ausente, autenticação HTTP, inicialização MCP e o usuário de runtime não root.

Teste ao vivo opcional (API SwitchBot real)

Execute somente quando quiser validar a conectividade real da API com suas próprias credenciais.

SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... npm run test:live
  • Usa a API SwitchBot real (não simulada)
  • Verificações somente leitura (list_devices e list_scenes)
  • Se as credenciais estiverem ausentes, o conjunto de testes ao vivo é ignorado

MCP Inspector (depuração manual)

Use o Inspector apenas para depuração manual local. Não o exponha a redes públicas.

npx @modelcontextprotocol/inspector node build/index.js

Passe variáveis de ambiente com -e, por exemplo:

npx @modelcontextprotocol/inspector \
  -e SWITCHBOT_TOKEN=... \
  -e SWITCHBOT_SECRET=... \
  -e MCP_TRANSPORT=stdio \
  -- node build/index.js

Este repositório não fixa o Inspector como dependência. Use npx para obter a versão corrigida mais recente.

Tratamento e remoção de dados

  • O servidor envia solicitações à API SwitchBot apenas para a origem oficial fixa da API. A substituição somente para teste é restrita a endereços de loopback.
  • As listas de dispositivos e cenas são armazenadas em cache apenas na memória do processo. O servidor não persiste dados de dispositivos SwitchBot, não executa análises, não envia telemetria nem realiza verificações automáticas de atualização.
  • Os logs operacionais são JSON estruturado em stderr. Campos com formato de credencial são mascarados, e os logs de operações da API não incluem identificadores de dispositivos ou cenas.
  • Para desinstalar, remova a configuração do cliente/servidor MCP e o pacote npm instalado ou contêiner. Remova ou rotacione as credenciais separadamente no gerenciador de segredos ou na configuração do cliente que as possui; este servidor não possui armazenamento persistente de credenciais para limpar.

Documentação do mantenedor

Política de gerenciamento de segredos

Use gerenciadores de segredos como armazenamento primário (AWS Secrets Manager, AWS SSM Parameter Store, Doppler). A injeção de variáveis de ambiente em tempo de execução é suportada, mas arquivos .env em texto simples não são o fluxo de trabalho primário recomendado.

Licença

ISC. Nomes e marcas SwitchBot pertencem aos seus respectivos proprietários; a licença de software não concede direitos de marca registrada.