@genm-dev/switchbot-mcp

SwitchBot MCP Server v3 for AI assistants.

日本語

Project status

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.

Build from source (available now)

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

Run `node build/index.js` with the required configuration below. The process

fails closed when credentials are missing.

Package install (after the first release)

One-click install

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.

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"
      }
    }
  }
}

Highlights

• 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

Requirements

• Node.js 24.15+
• SwitchBot Open API token and secret

Install

Available after the first release:

npm install @genm-dev/switchbot-mcp

Configuration

Required

• `SWITCHBOT_TOKEN`
• `SWITCHBOT_SECRET`

Transport

• `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.

Runtime

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

Test-only (optional)

• `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.

MCP tools (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` (advanced, raw upstream fields)

See migration details: docs/migration-v2-to-v3.md

Usage

stdio (package / npx, after the first release)

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

stdio (local development build)

{
  "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`

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.

Optional third-party integration: Smithery

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 claude

Testing strategy

Required gates (deterministic)

npm run check
npm run test:coverage

`npm 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:container

This verifies missing-configuration failure, HTTP authentication, MCP

initialization, and the non-root runtime user.

Optional live test (real SwitchBot API)

Run this only when you want to validate real API connectivity with your own credentials.

SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... npm run test:live

• Uses real SwitchBot API (not mocked)
• Read-only checks (`list_devices` and `list_scenes`)
• If credentials are missing, the live test suite is skipped

MCP Inspector (manual debugging)

Use Inspector only for local manual debugging. Do not expose it to public networks.

npx @modelcontextprotocol/inspector node build/index.js

Pass env vars with `-e`, for example:

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

This repository does not pin Inspector as a dependency. Use `npx` to get the latest patched release.

Data handling and removal

• 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.

Maintainer docs

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• GOVERNANCE.md
• SECURITY.md
• docs/security-model.md
• SUPPORT.md
• docs/github-flow.md
• docs/release-process.md

Secrets management policy

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.

License

ISC. SwitchBot names and marks belong to their respective owners;

the software license does not grant trademark rights.