SwitchBot

Controla los dispositivos inteligentes SwitchBot a través de su API oficial, permitiendo la automatización e integración con asistentes de IA.

GitHub
7
Prueba este MCPPatrocinado

Documentación

@genm-dev/switchbot-mcp

Servidor MCP de SwitchBot v3 para asistentes de IA.

License CI CodeQL

日本語

Estado del proyecto

El repositorio fuente es público, pero la v3 aún no se ha publicado en npm ni en el Registro MCP oficial. Los comandos npm, npx y de un clic en este README solo estarán disponibles después del primer lanzamiento registrado en Issue #7. Compila desde el código fuente para la evaluación actual.

Esta es una integración comunitaria no oficial y no está afiliada ni respaldada por SwitchBot. Las llamadas a herramientas pueden controlar dispositivos físicos y ejecutar escenas. Revisa las acciones solicitadas, el acceso a credenciales y la exposición de red antes de usarla; no trates la confirmación de un cliente de IA como un límite de autorización.

Compilar desde el código fuente (disponible ahora)

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

Ejecuta node build/index.js con la configuración requerida a continuación. El proceso falla de forma segura cuando faltan credenciales.

Instalación del paquete (después del primer lanzamiento)

Instalación con un clic

Install in Cursor Install in VS Code

Estos enlaces actualmente apuntan al paquete npm público planificado. Después de la publicación, reemplaza SWITCHBOT_TOKEN y SWITCHBOT_SECRET con tus credenciales y revisa la configuración antes de iniciar el 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"
      }
    }
  }
}

Características destacadas

  • v3.0.0 en la plataforma Node.js 24 LTS
  • MCP SDK v2 con cobertura explícita de negociación del protocolo MCP 2026-07-28
  • fetch nativo con validación estricta de respuestas del proveedor
  • Arquitectura en capas (cliente SwitchBot / herramientas MCP / transportes)
  • Transportes stdio y Streamable HTTP
  • Clave API requerida para el transporte HTTP
  • Validación de Origin y Host del mismo servidor para despliegues HTTP
  • Salidas de herramientas MCP estructuradas (structuredContent)
  • Anotaciones de riesgo MCP y reintentos limitados para solicitudes de solo lectura de SwitchBot
  • Registros operativos JSONL con datos sensibles redactados
  • CI de repositorio público en runtimes, artefactos de paquete y contenedores compatibles

Requisitos

  • Node.js 24.15+
  • Token y secreto de la API abierta de SwitchBot

Instalación

Disponible después del primer lanzamiento:

npm install @genm-dev/switchbot-mcp

Configuración

Requerido

  • SWITCHBOT_TOKEN
  • SWITCHBOT_SECRET

Transporte

  • MCP_TRANSPORT=stdio|http (predeterminado: stdio)
  • MCP_SERVER_API_KEY (requerido para http; usa un secreto de alta entropía sin espacios en blanco alrededor)
  • MCP_HTTP_HOST (predeterminado: 127.0.0.1)
  • MCP_HTTP_ALLOWED_HOSTS (nombres de host de proxy/públicos opcionales separados por comas)
  • MCP_HTTP_PORT (predeterminado: 8787)
  • MCP_HTTP_PATH (predeterminado: /mcp)

Las solicitudes HTTP con un encabezado Origin deben usar un nombre de host de la misma lista de permitidos que el encabezado Host. Localhost y el host de enlace configurado se incluyen automáticamente. Agrega nombres de host de proxy inverso explícitamente; las solicitudes malformadas o de origen cruzado se rechazan.

Tiempo de ejecución

  • SWITCHBOT_TIMEOUT_MS (predeterminado: 10000)
  • SWITCHBOT_LIST_CACHE_TTL_MS (predeterminado: 30000)
  • LOG_LEVEL=debug|info|warn|error (predeterminado: info)

Solo pruebas (opcional)

  • SWITCHBOT_BASE_URL (anula el endpoint de la API de SwitchBot para pruebas e2e deterministas)

La anulación solo se acepta cuando NODE_ENV=test y la URL usa localhost, 127.0.0.0/8 o [::1]. Esto evita que las credenciales de producción se redirijan a otro origen.

Herramientas 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 (avanzado, campos sin procesar del proveedor)

Consulta los detalles de migración: docs/migration-v2-to-v3.md

Uso

stdio (paquete / npx, después del primer lanzamiento)

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

stdio (compilación de desarrollo 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

Genera la credencial de portador con un generador criptográficamente seguro, por ejemplo openssl rand -hex 32, e inyéctala desde tu administrador de secretos. El servidor Node habla HTTP plano. Para cualquier despliegue que no sea de bucle local, termina TLS en un proxy inverso de confianza, restringe el acceso de red y configura su nombre de host en MCP_HTTP_ALLOWED_HOSTS; no expongas el listener de Node directamente a Internet público.

Integración opcional de terceros: Smithery

Smithery no es un canal de distribución oficial para este proyecto. npm, el Registro MCP oficial y las configuraciones directas de cliente anteriores son las rutas canónicas de instalación y descubrimiento.

La configuración de Smithery conservada usa su formato de repositorio heredado y no se ha revalidado contra el modelo de publicación MCPB/URL actual de Smithery. El comando a continuación es informativo y no debe anunciarse como compatible hasta que se verifique por separado después del primer lanzamiento.

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

Estrategia de pruebas

Puertas requeridas (deterministas)

npm run check
npm run test:coverage

npm run check incluye verificación de tipos, linting, formato, pruebas de protocolo y transporte MCP, una compilación, validación de metadatos del paquete, instalación/ejecución del artefacto empaquetado y un SBOM de dependencias de producción validado. npm run test:coverage aplica umbrales de cobertura.

Al cambiar el runtime de Docker, también ejecuta:

npm run smoke:container

Esto verifica el fallo por configuración faltante, la autenticación HTTP, la inicialización de MCP y el usuario de runtime no root.

Prueba en vivo opcional (API real de SwitchBot)

Ejecuta esto solo cuando quieras validar la conectividad real de la API con tus propias credenciales.

SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... npm run test:live
  • Usa la API real de SwitchBot (no simulada)
  • Verificaciones de solo lectura (list_devices y list_scenes)
  • Si faltan credenciales, el conjunto de pruebas en vivo se omite

MCP Inspector (depuración manual)

Usa Inspector solo para depuración manual local. No lo expongas a redes públicas.

npx @modelcontextprotocol/inspector node build/index.js

Pasa variables de entorno con -e, por ejemplo:

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

Este repositorio no fija Inspector como dependencia. Usa npx para obtener la última versión con parches.

Manejo y eliminación de datos

  • El servidor envía solicitudes a la API de SwitchBot solo al origen oficial fijo de la API. La anulación solo para pruebas está restringida a direcciones de bucle local.
  • Las listas de dispositivos y escenas se almacenan en caché solo en la memoria del proceso. El servidor no persiste datos de dispositivos de SwitchBot, no ejecuta análisis, no envía telemetría ni realiza verificaciones automáticas de actualizaciones.
  • Los registros operativos son JSON estructurado en stderr. Los campos con forma de credencial se redactan, y los registros de operaciones de API no incluyen identificadores de dispositivos o escenas.
  • Para desinstalar, elimina la configuración del cliente/servidor MCP y el paquete npm o contenedor instalado. Elimina o rota las credenciales por separado en el administrador de secretos o la configuración del cliente que las posee; este servidor no tiene un almacén de credenciales persistente que limpiar.

Documentación para mantenedores

Política de gestión de secretos

Usa administradores de secretos como almacenamiento principal (AWS Secrets Manager, AWS SSM Parameter Store, Doppler). Se admite la inyección de variables de entorno en tiempo de ejecución, pero los archivos .env en texto plano no son el flujo de trabajo principal recomendado.

Licencia

ISC. Los nombres y marcas de SwitchBot pertenecen a sus respectivos propietarios; la licencia de software no otorga derechos de marca comercial.