SwitchBot CLI
SwitchBot smart-home CLI for devices and scenes, with a built-in MCP server for Claude Code, Codex and Gemini CLI.
- 136 ★ on the repository
- Last commit
Broad access
Why this level
- Controls physical devices: locks, garage doors and plugs.
- Stores the SwitchBot token and secret in the OS keychain or in `~/.switchbot/config.json`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/switchbot-cliDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Controls physical devices: locks, garage doors and plugs.
- Stores the SwitchBot token and secret in the OS keychain or in `~/.switchbot/config.json`.
This is third-party code. Review the repository files before installing.
What it does
The `@switchbot/openapi-cli` package provides a `switchbot` command for SwitchBot devices, scenes and event streams. One device catalog, cache and HMAC request signer serve humans, scripts and agents alike. For agents there is `switchbot mcp serve` with 18 tools by default, 15 in read-only mode and 29 with `--tools all`. The `switchbot claude-code setup`, `codex setup` and `gemini setup` commands register the server themselves and open a browser login, with keys stored in the OS keychain. Guards cover risky commands: `--dry-run`, `--require-approval` and an `--audit-log` journal.
Who it is for. SwitchBot smart-home owners who want to control lights, curtains and locks from an agent chat or a script.
Good fit when
- An agent turns on an evening lighting scene from one sentence.
- You need a device list in JSON for a script.
- Door sensors are read through the MQTT event stream.
- Risky commands are first checked with the `--dry-run` flag.
Not a fit when
- Devices come from another manufacturer.
- A lock or garage door must not open without human confirmation.
- Only Node.js older than version 18 is available.
Example request
List my SwitchBot devices and turn off the living-room light, checking the command with `--dry-run` first.Limitations
Node.js 18 or newer and a SwitchBot account are required. Cameras report status only, and sensors and hubs are read-only. Device capabilities follow the official API documentation, and behaviour of undocumented modes is not certified. The 0.2.0 Codex and Gemini plugins need CLI 3.9.0 or newer. The Gemini CLI extension is linked with `gemini extensions link`, and the Codex plugin is a separate package. Policy automations need `policy.yaml` to be set up.
How to disable. Remove the MCP server from your client configuration, run `npm uninstall -g @switchbot/openapi-cli` and erase the keys from the keychain with `switchbot auth keychain delete`.
FAQ
How do I connect SwitchBot to Claude Code?
Run `npx @switchbot/openapi-cli claude-code setup` and restart Claude Code. The command installs the CLI, registers the MCP server through `claude mcp add --scope user` and opens a browser login.
Do I need to copy a token from the app?
No, `switchbot auth login` is enough. The token and secret from the app are needed only for manual setup with `switchbot config set-token`.
How many tools does the MCP server have?
18 by default, 15 in read-only mode and 29 with `--tools all`.
How do I verify the install?
Run `switchbot doctor`: 22 checks cover Node, credentials, MQTT, policy and the audit log.
How do I protect a lock from an accidental command?
Check the command with `--dry-run`, enable `--require-approval` in `plan run` and keep an `--audit-log`. In read-only mode the MCP server does not send commands.
Discussion
No questions or reviews yet.
Related
CLI toolsAn MCP server in a single Go binary: more than 75 local tools for files, shell, browser, calendar and scheduled tasks
A Claude Code plugin and MCP server: the agent switches lights, locks doors and runs Apple HomeKit scenes from a Mac
Connects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
Discord MCP by cappyeo: a server with 200+ tools
Discord MCP (cappyeo)
A Discord MCP with over 200 typed tools: the agent handles messages, roles and moderation, builds a server from a plan, and writes default to preview mode
A Node.js MCP server through which an agent controls Home Assistant devices and edits its automations
Hycli turns a website URL and a goal into a typed CLI and MCP tools that run in your own browser session, with no cookie leaks.
README in short
Three entry points: for humans (tables, hints, completion), scripts (`--json`, exit codes, audit log) and agents (`mcp serve`, `schema export`, `plan run`). Automation policies live in `policy.yaml`.