The SwitchBot MCP Server enables AI assistants to interact with and control SwitchBot devices. With this server, you can:
List available devices
Get device status (requires deviceId)
Control devices (turn on/off; requires deviceId and command)
Change device settings
Scene control (list and execute scenes)
Device status monitoring (temperature, humidity, brightness, motion)
Supported devices include Plugs, Bots, Curtains, Air Conditioners, Humidifiers, Lights, and Remote Controls.
Provides connectivity for SwitchBot devices which operate over Bluetooth, allowing device control for devices within Bluetooth range.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SwitchBot MCP Server turn on the living room AC"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SwitchBot MCP Server v3 for AI assistants.
The source repository is public, but v3 is not yet published to npm or the
official MCP Registry. The npm, npx, and one-click commands in this README
become usable only after the first release tracked in
Issue #7. Build from source for
current evaluation.
This is an unofficial community integration and is not affiliated with or endorsed by SwitchBot. Tool calls can control physical devices and execute scenes. Review requested actions, credential access, and network exposure before use; do not treat an AI client's confirmation as an authorization boundary.
Related MCP server: MCP Govee
git clone https://github.com/genm/switchbot-mcp.git
cd switchbot-mcp
npm ci --ignore-scripts
npm run buildRun node build/index.js with the required configuration below. The process
fails closed when credentials are missing.
These links currently target the planned public npm package. After publication,
replace SWITCHBOT_TOKEN and SWITCHBOT_SECRET with your credentials and review
the configuration before starting the server.
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"}}'{
"mcpServers": {
"switchbot": {
"command": "npx",
"args": ["-y", "@genm-dev/switchbot-mcp"],
"env": {
"SWITCHBOT_TOKEN": "YOUR_SWITCHBOT_TOKEN",
"SWITCHBOT_SECRET": "YOUR_SWITCHBOT_SECRET",
"MCP_TRANSPORT": "stdio"
}
}
}
}v3.0.0 on the Node.js 24 LTS platform
MCP SDK v2 with explicit MCP 2026-07-28 protocol negotiation coverage
Native fetch with strict upstream response validation
Layered architecture (SwitchBot client / MCP tools / transports)
stdio and Streamable HTTP transports
API key required for HTTP transport
Same-host Origin and Host validation for HTTP deployments
Structured MCP tool outputs (structuredContent)
MCP risk annotations and bounded retries for read-only SwitchBot requests
Redacted JSONL operational logs
Public-repository CI across supported runtimes, package artifacts, and containers
Node.js 24.15+
SwitchBot Open API token and secret
Available after the first release:
npm install @genm-dev/switchbot-mcpSWITCHBOT_TOKEN
SWITCHBOT_SECRET
MCP_TRANSPORT=stdio|http (default: stdio)
MCP_SERVER_API_KEY (required for http; use a high-entropy secret without surrounding whitespace)
MCP_HTTP_HOST (default: 127.0.0.1)
MCP_HTTP_ALLOWED_HOSTS (optional comma-separated proxy/public hostnames)
MCP_HTTP_PORT (default: 8787)
MCP_HTTP_PATH (default: /mcp)
HTTP requests with an Origin header must use a hostname from the same
allowlist as the Host header. Localhost and the configured bind host are
included automatically. Add reverse-proxy hostnames explicitly; malformed or
cross-origin requests are rejected.
SWITCHBOT_TIMEOUT_MS (default: 10000)
SWITCHBOT_LIST_CACHE_TTL_MS (default: 30000)
LOG_LEVEL=debug|info|warn|error (default: info)
SWITCHBOT_BASE_URL (override SwitchBot API endpoint for deterministic e2e tests)
The override is accepted only when NODE_ENV=test and the URL uses
localhost, 127.0.0.0/8, or [::1]. This prevents production credentials
from being redirected to another origin.
switchbot_list_devices
switchbot_get_device_status
switchbot_set_power
switchbot_send_command
switchbot_list_scenes
switchbot_execute_scene
switchbot_list_devices_raw (advanced, raw upstream fields)
See migration details: docs/migration-v2-to-v3.md
{
"mcpServers": {
"switchbot": {
"command": "npx",
"args": ["-y", "@genm-dev/switchbot-mcp"],
"env": {
"SWITCHBOT_TOKEN": "...",
"SWITCHBOT_SECRET": "...",
"MCP_TRANSPORT": "stdio"
}
}
}
}{
"mcpServers": {
"switchbot": {
"command": "node",
"args": ["/absolute/path/to/build/index.js"],
"env": {
"SWITCHBOT_TOKEN": "...",
"SWITCHBOT_SECRET": "...",
"MCP_TRANSPORT": "stdio"
}
}
}
}MCP_TRANSPORT=http \
MCP_SERVER_API_KEY=your_api_key \
SWITCHBOT_TOKEN=... \
SWITCHBOT_SECRET=... \
npx -y @genm-dev/switchbot-mcpEndpoint: http://127.0.0.1:8787/mcp
Generate the bearer credential with a cryptographically secure generator, for
example openssl rand -hex 32, and inject it from your secret manager. The Node
server speaks plain HTTP. For any non-loopback deployment, terminate TLS at a
trusted reverse proxy, restrict network access, and configure its hostname in
MCP_HTTP_ALLOWED_HOSTS; do not expose the Node listener directly to the public
internet.
Smithery is not an official distribution channel for this project. npm, the Official MCP Registry, and the direct client configurations above are the canonical installation and discovery paths.
The retained Smithery configuration uses its legacy repository format and has not been revalidated against Smithery's current MCPB/URL publication model. The command below is informational and must not be advertised as supported until it is verified separately after the first release.
npx -y @smithery/cli@latest install @genm-dev/switchbot-mcp --client claudenpm run check
npm run test:coveragenpm run check includes type-checking, linting, formatting, MCP protocol and
transport tests, a build, package metadata validation, installation/execution
of the packed artifact, and a validated production-dependency SBOM. npm run test:coverage enforces coverage thresholds.
When changing the Docker runtime, also run:
npm run smoke:containerThis verifies missing-configuration failure, HTTP authentication, MCP initialization, and the non-root runtime user.
Run this only when you want to validate real API connectivity with your own credentials.
SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... npm run test:liveUses real SwitchBot API (not mocked)
Read-only checks (list_devices and list_scenes)
If credentials are missing, the live test suite is skipped
Use Inspector only for local manual debugging. Do not expose it to public networks.
npx @modelcontextprotocol/inspector node build/index.jsPass env vars with -e, for example:
npx @modelcontextprotocol/inspector \
-e SWITCHBOT_TOKEN=... \
-e SWITCHBOT_SECRET=... \
-e MCP_TRANSPORT=stdio \
-- node build/index.jsThis repository does not pin Inspector as a dependency. Use npx to get the latest patched release.
The server sends SwitchBot API requests only to the fixed official API origin. The test-only override is restricted to loopback addresses.
Device and scene lists are cached in process memory only. The server does not persist SwitchBot device data, run analytics, send telemetry, or perform automatic update checks.
Operational logs are structured JSON on stderr. Credential-shaped fields are redacted, and API operation logs do not include device or scene identifiers.
To uninstall, remove the MCP client/server configuration and the installed npm package or container. Remove or rotate credentials separately in the secret manager or client configuration that owns them; this server has no persistent credential store to clean up.
Use secret managers as primary storage (AWS Secrets Manager, AWS SSM Parameter Store, Doppler).
Environment variable injection at runtime is supported, but plaintext .env files are not the recommended primary workflow.
ISC. SwitchBot names and marks belong to their respective owners; the software license does not grant trademark rights.
デバイスを制御します
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | Yes | デバイスID | |
| command | Yes | コマンド（turnOn, turnOff） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'デバイスを制御します' only states the action without revealing any behavioral traits: it doesn't indicate whether this is a read or write operation (though 'control' implies mutation), what permissions are required, whether changes are reversible, what side effects occur, or what the response looks like. For a device control tool with zero annotation coverage, this is completely inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is technically concise (a single phrase), this represents under-specification rather than effective brevity. The single sentence 'デバイスを制御します' doesn't earn its place by providing meaningful information beyond what's already implied by the tool name. True conciseness balances brevity with information density, which this description fails to achieve.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a device control tool (implying mutation) with no annotations, no output schema, and a minimal description, the description is completely inadequate. The agent needs to understand what 'control' means operationally, what happens when commands are executed, what the response contains, and how this differs from sibling tools. The current description provides none of this essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters ('deviceId' and 'command') fully documented in the schema. The description adds no additional meaning about parameters beyond what the schema already provides. According to the scoring rules, when schema coverage is high (>80%), the baseline score is 3 even with no parameter information in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'デバイスを制御します' (controls devices) is a tautology that essentially restates the tool name 'control_device' in Japanese. It doesn't specify what kind of control is performed or differentiate this tool from its siblings 'get_device_status' and 'list_devices'. While it indicates the general domain (device control), it lacks specificity about the verb and resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There's no mention of when to use 'control_device' instead of 'get_device_status' or 'list_devices', nor any context about prerequisites, appropriate scenarios, or exclusions. The agent receives no usage direction beyond the tool name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
デバイスのステータスを取得します
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | Yes | デバイスID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description only states what the tool does ('get device status') without mentioning any behavioral traits such as whether it's read-only, requires authentication, has rate limits, returns specific data formats, or handles errors. This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, with zero waste, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the status includes (e.g., online/offline, metrics), how results are returned, or any error conditions. For a tool with no structured behavioral or output information, the description should provide more context to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'deviceId' documented as 'デバイスID' (device ID). The description adds no additional meaning beyond what the schema provides, such as explaining what constitutes a valid device ID or how to obtain it. With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose ('デバイスのステータスを取得します' translates to 'Get device status'), which is a clear verb+resource combination. However, it doesn't differentiate from sibling tools like 'list_devices' (which might list multiple devices) or 'control_device' (which performs actions rather than retrieving status). The purpose is understandable but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There are no explicit instructions about when to use 'get_device_status' instead of 'list_devices' or 'control_device', nor any context about prerequisites or exclusions. This leaves the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
デバイス一覧を取得します
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. The description only states what the tool does ('get device list') but doesn't disclose behavioral traits like whether this requires authentication, returns paginated results, has rate limits, or what format the output takes. For a tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence that directly states the tool's purpose. No wasted words or unnecessary elaboration. Perfectly front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotations, no output schema, and a simple list operation, the description is incomplete. It doesn't explain what the output looks like (list format, fields included), whether there are any constraints or prerequisites, or how this differs meaningfully from sibling tools. The description provides minimal context beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage (empty schema). The description doesn't need to explain parameters since there are none. Baseline for 0 parameters is 4, as the description correctly doesn't attempt to document nonexistent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'デバイス一覧を取得します' (Get device list) clearly states the action (取得/retrieve) and resource (デバイス一覧/device list). It distinguishes from siblings like 'control_device' (which modifies) and 'get_device_status' (which gets status of individual devices). However, it doesn't specify scope (all devices? filtered?) which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description doesn't mention when to use list_devices versus get_device_status (for individual device status) or control_device (for device control). Usage context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with no overlap: control_device performs actions on devices, get_device_status retrieves status information, and list_devices enumerates available devices. The descriptions clearly differentiate between controlling, checking status, and listing devices.
All three tools follow a consistent verb_noun pattern with snake_case naming: control_device, get_device_status, and list_devices. The naming is perfectly uniform and predictable across the entire tool set.
With only 3 tools, the count feels somewhat thin for a device control server that might benefit from more granular operations like specific device types or advanced controls. However, it covers the absolute basics adequately.
The tools provide basic CRUD-like coverage for device management (list, get status, control), but there are notable gaps such as no ability to create/configure new devices, delete devices, or handle device groups/scenes. The surface is functional but minimal.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Control your Tesla from your AI assistant - climate, charging, access, and security.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Connects AI assistants to CloudQuell multi-cloud and AI cost, savings, anomaly, and budget data.
Connect AI assistants to Subotiz - Using Subotiz's external capabilities through natural language
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/genm/switchbot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
