SwitchBot MCP Server

SwitchBot MCP Server is a server application that integrates with the SwitchBot API, allowing control and monitoring of SwitchBot devices through the Model Context Protocol (MCP). It enables MCP clients (such as Claude Desktop) to discover SwitchBot devices, retrieve their status, and send commands.

Project Structure

This project is organized as a multi-module Gradle build:

• switchbot-client: A Kotlin Multiplatform (KMP) client library for interacting with the SwitchBot API. It handles authentication and API requests.
• switchbot-mcp-server: A Quarkus-based MCP server implementation that exposes SwitchBot device functionalities as MCP tools.

Features

The MCP server provides the following tools for SwitchBot devices:

• listDevices: Retrieves a comprehensive list of all physical SwitchBot devices configured in the user's account.
• listInfraredRemotes: Retrieves a list of virtual infrared remote control devices.
• getDeviceStatus: Fetches the current status (e.g., power state, temperature, humidity, battery level) of a specified device.
• sendCommand: Sends various control commands (e.g., turn on/off, set position, adjust brightness) to compatible devices.

Device-specific tools are dynamically registered based on the actual devices connected to the user's SwitchBot account. Currently implemented device-specific tools include:

• Bot: pressBot, turnOnBot, turnOffBot
• Curtain: setPositionCurtain, openCurtain, closeCurtain, pauseCurtain
• Blind Tilt / Roller Shade: setPositionBlindTilt, fullyOpenBlindTilt, closeUpBlindTilt, closeDownBlindTilt, setPositionRollerShade
• Humidifier: turnOnHumidifier, turnOffHumidifier, setHumidifierMode, setEvaporativeHumidifierChildLock (for Humidifier2)
• Light: turnOnLight, turnOffLight, toggleLight, setBrightnessLight, setColorLight, setColorTemperatureLight
• Plug: turnOnPlug, turnOffPlug, togglePlug, setPlugMode, turnOnPlugChannel, turnOffPlugChannel, togglePlugChannel, setPlugModeChannel, setPlugPosition
• Robot Vacuum: startVacuum, stopVacuum, dockVacuum, setVacuumPowLevel, startCleanVacuum, pauseVacuum, setVacuumVolume
• Smart Radiator Thermostat: turnOnThermostat, turnOffThermostat, setThermostatMode, setThermostatManualTemp
• Circulator Fan: turnOnFan, turnOffFan, setFanNightLightMode, setFanWindMode, setFanWindSpeed, setFanCloseDelay
• Smart Lock: lockLock, unlockLock, deadboltLock (for Pro/Ultra models)
• Candle Warmer Lamp: turnOnCandleWarmerLamp, turnOffCandleWarmerLamp, toggleCandleWarmerLamp, setBrightnessCandleWarmerLamp
• AI Art Frame: nextAiArtFrame, previousAiArtFrame
• Garage Door Opener: openGarageDoor, closeGarageDoor

Prerequisites

• Java 17 or higher (for running the server)
• SwitchBot API credentials (Open Token and Secret Key)
  • You can obtain these by following the instructions here.

Configuration

Set the following environment variables or specify them in switchbot-mcp-server/src/main/resources/application.properties.

Property	Environment Variable	Description
switchbot.api.token	SWITCHBOT_API_TOKEN	Your SwitchBot API Open Token
switchbot.api.secret	SWITCHBOT_API_SECRET	Your SwitchBot API Secret Key
switchbot.registration.enabled	SWITCHBOT_REGISTRATION_ENABLED	Set to false to disable dynamic tool registration (useful for tests). Defaults to true.

Usage

Building and Running the Executable JAR (Uber-JAR)

To build the self-contained executable JAR and run the server, execute the following commands from the project root:

./gradlew :switchbot-mcp-server:build -Dquarkus.package.jar.type=uber-jar
java -jar switchbot-mcp-server/build/switchbot-mcp-server.jar

Ensure that the SWITCHBOT_API_TOKEN and SWITCHBOT_API_SECRET environment variables are set or configured in application.properties before running.

Running with Docker

To build and run the Docker image, execute the following commands from the project root:

docker build -f switchbot-mcp-server/src/main/docker/Dockerfile -t switchbot-mcp-server .
docker run -i --rm -p 8080:8080 \
  -e SWITCHBOT_API_TOKEN=your_token \
  -e SWITCHBOT_API_SECRET=your_secret \
  switchbot-mcp-server

Registration with MCP Clients

To integrate with an MCP client (e.g., Claude Desktop), configure it to launch this server. An example configuration entry for claude_desktop_config.json might look like this:

{
  "mcpServers": {
    "switchbot": {
      "command": "java",
      "args": [
        "-jar",
        "path/to/switchbot-mcp-server/build/switchbot-mcp-server.jar"
      ],
      "env": {
        "SWITCHBOT_API_TOKEN": "YOUR_TOKEN",
        "SWITCHBOT_API_SECRET": "YOUR_SECRET"
      }
    }
  }
}

Note: The current implementation primarily uses Server-Sent Events (SSE) for MCP communication. Depending on your MCP client's capabilities, you may need to adjust the server configuration or client integration to use other communication methods (e.g., standard input/output).

License

Apache License 2.0