Switchr Server

A Node.js MCP (Model Context Protocol) server that exposes SwitchBot temperature sensors for monitoring via Claude Desktop or Home Assistant.

Features

• Device Discovery: Automatically discovers all SwitchBot devices (Meter, MeterPlus, WoIOSensor, Plug Mini, Bot)
• Temperature Monitoring: Read temperature and humidity from any sensor
• Energy Monitoring: Read power, voltage, and current from Plug Mini devices (UPS/load monitoring)
• Switching: Turn plugs on/off, press Bot finger simulators
• Flexible Units: Support for both Fahrenheit and Celsius
• Device Lookup: Find devices by ID or nickname (case-insensitive)
• Dual Transport: Supports both stdio (Claude Desktop) and HTTP/SSE (Home Assistant)
• Request Logging: Optional logging of all tool calls for debugging

Installation

cd switchr-mcp
npm install

Configuration

SwitchBot Credentials

SwitchBot API credentials are managed by @caseman72/switchr-api via .env.local. The file is searched in:

1. Current working directory
2. ~/.config/switchr-api/.env.local
3. ~/.switchbot.env.local

Create a .env.local file with your SwitchBot credentials:

SWITCHBOT_TOKEN=your-switchbot-token
SWITCHBOT_SECRET=your-switchbot-secret

Visit the SwitchBot Developer Portal to obtain your API credentials.

Server Configuration (Optional)

Copy config.example.json to config.json to customize server settings:

{
  "server": {
    "transport": "stdio",
    "httpPort": 8001,
    "httpHost": "127.0.0.1"
  },
  "devices": {
    "refreshIntervalMinutes": 60
  },
  "monitoring": {
    "enabled": false,
    "logFile": "./switchr-mcp-requests.log"
  }
}

Usage

stdio Transport (Claude Desktop)

node src/index.js

HTTP Transport (Home Assistant)

The HA custom component requires the MCP server to be exposed over HTTP/SSE. Use mcp-proxy to bridge the stdio server.

Install mcp-proxy

brew install mcp-proxy

Start the proxy

# Binds to all interfaces so Docker can reach it
mcp-proxy --port 8082 --host 0.0.0.0 -- node /path/to/switchr-mcp/src/index.js

Home Assistant Integration

1. Copy the custom component to your HA config directory:

   cp -r custom_components/switchr_mcp ~/.home-assistant/custom_components/
   

2. Restart Home Assistant

3. Add the integration: Settings → Devices & Services → Add Integration → "Switchr MCP"

4. Enter connection details:

   • Host: host.docker.internal (for Docker) or your Mac's IP
   • Port: 8082

Entities created

• Temperature sensors (Meter, MeterPlus, WoIOSensor): one combined entity per device with temperature as the native value and humidity/battery as attributes.
• Plug Mini: four sensors plus a switch — <name> Power (W), <name> Voltage (V), <name> Current (mA), <name> Energy (kWh), and switch.<name> (on/off control). The Energy entity integrates instantaneous power between polls and persists across HA restarts via RestoreEntity, so it can be used directly in the HA Energy dashboard with no Riemann helper.
• Bot (finger simulator): button.<name>_press — sends a momentary press (extend then retract). Suitable for pressMode Bots.

Auto-start mcp-proxy with launchd

Create ~/Library/LaunchAgents/com.switchr.mcp-proxy.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.switchr.mcp-proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/mcp-proxy</string>
        <string>--port</string>
        <string>8082</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--</string>
        <string>/opt/homebrew/bin/node</string>
        <string>/path/to/switchr-mcp/src/index.js</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/switchr-mcp</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/switchr-mcp-proxy.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/switchr-mcp-proxy.err</string>
</dict>
</plist>

Then load it:

launchctl load ~/Library/LaunchAgents/com.switchr.mcp-proxy.plist

To stop/unload:

launchctl unload ~/Library/LaunchAgents/com.switchr.mcp-proxy.plist

Managing the service

# Check status
launchctl list | grep switchr

# View logs
tail -f /tmp/switchr-mcp-proxy.err

# Restart
launchctl unload ~/Library/LaunchAgents/com.switchr.mcp-proxy.plist
launchctl load ~/Library/LaunchAgents/com.switchr.mcp-proxy.plist

# Stop
launchctl unload ~/Library/LaunchAgents/com.switchr.mcp-proxy.plist

Claude Desktop Integration

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "switchr": {
      "command": "node",
      "args": ["/path/to/switchr-mcp/src/index.js"],
      "env": {}
    }
  }
}

MCP Tools

list_devices

List all discovered SwitchBot devices. Optionally filter to show only temperature sensors.

Parameters:

• sensorsOnly (optional): If true, only return temperature sensors (Meter, MeterPlus, WoIOSensor)
• refresh (optional): Force refresh device list from SwitchBot API

get_device_status

Get detailed status of any SwitchBot device. Returns device-specific properties like power state, battery level, etc.

Parameters:

• deviceId: Device ID or device name

get_temperature

Get temperature and humidity reading from a specific SwitchBot temperature sensor.

Parameters:

• deviceId: Device ID or device name of the temperature sensor
• unit (optional): Temperature unit - F for Fahrenheit (default), C for Celsius

Response includes:

• temperature: Current temperature in requested unit
• humidity: Current humidity percentage
• battery: Battery level percentage

get_all_temperatures

Get temperature and humidity readings from all SwitchBot temperature sensors at once.

Parameters:

• unit (optional): Temperature unit - F for Fahrenheit (default), C for Celsius

get_plug_status

Get power state and energy data from a SwitchBot Plug Mini. Use for UPS/energy monitoring.

Parameters:

• deviceId: Device ID or device name of the plug

Response includes:

• power: "on" or "off"
• voltage: Volts
• watts: Instantaneous power draw (W)
• currentMilliamps: Current draw (mA)
• electricityOfDay: Today's on-time accumulator from the device

get_all_plugs

Get power and energy readings from all SwitchBot Plug Mini devices at once.

turn_on / turn_off

Turn a SwitchBot Plug Mini (or a Bot in switch mode) on/off.

Parameters:

• deviceId: Device ID or device name

press_bot

Send a momentary press to a SwitchBot Bot (finger simulator). The finger extends then retracts.

Parameters:

• deviceId: Device ID or device name of the Bot

get_api_status

Get SwitchBot API rate limit status. Returns remaining calls, reset time, and cache info.

Response includes:

• rate_limit.remaining: API calls remaining
• rate_limit.reset_by: When the rate limit resets
• cache.last_refresh: When devices were last refreshed
• cache.device_count: Total devices discovered
• cache.sensor_count: Temperature sensors discovered

Request Monitoring

Enable request logging in config.json:

{
  "monitoring": {
    "enabled": true,
    "logFile": "./switchr-mcp-requests.log"
  }
}

Logs are written in JSON Lines format with timestamps, tool names, parameters, and results.

License

MIT