@genm-dev/switchbot-mcp

SwitchBot MCP Server v3 for AI assistants.

日本語

Quick Install

One-click install

Replace SWITCHBOT_TOKEN and SWITCHBOT_SECRET with your credentials after
installation. The links install the public npm package through npx; 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
• 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
• Structured MCP tool outputs (structuredContent)
• Public-repository CI across supported runtimes, package artifacts, and containers

Requirements

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

Install

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)
• MCP_HTTP_HOST (default: 127.0.0.1)
• MCP_HTTP_PORT (default: 8787)
• MCP_HTTP_PATH (default: /mcp)

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)

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)

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

Alternative install (Smithery)

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, and installation/execution
of the packed artifact. 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.

Maintainer docs

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