AI导哈

SwitchBot设备控制服务器

一个基于Model Context Protocol (MCP)的服务器，用于通过Claude Desktop控制SwitchBot设备，支持动态工具生成和自动认证。

  • by kta
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 kta/mcp-switchbot-go

使用说明

SwitchBot MCP服务器（Go）

日语版在这里

A. 模型上下文协议（MCP） 使Claude Desktop能够控制SwitchBot设备的服务器。

特性

  • 183工具：完整覆盖SwitchBot API v1.1
  • 动态工具生成：根据YAML规范自动生成工具
  • 自动工具名称消毒：Auto符合MCP命名约定（转换括号等）
  • 自动更新：启动/生成时自动下载最新的API规范
  • HMAC-SHA256身份验证：SwitchBot API身份验证的自动处理
  • 本地/k8s支持：运行二进制、Docker容器或Kubernetes部署

需求

  • 转到1.23+（用于当地发展）
  • Docker（用于容器执行）
  • Kubernetes（用于生产部署）
  • SwitchBot API令牌和机密

正在获取SwitchBot API凭据

  1. 访问 SwitchBot官方网站
  2. 在应用程序中，转到个人资料→ 设置→ 点击“应用程序版本”10次以启用开发者模式
  3. 获取您的“令牌”并将其另存为 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET

有关详细信息，请参阅 SwitchBot API文档.

本地开发

1.设置环境变量

cp .env.example .env
# Edit .env file to set your token and secret

2.构建和运行

# Build
make build

# Run
export SWITCHBOT_TOKEN='your_token'
export SWITCHBOT_SECRET='your_secret'
./mcp-switchbot

或者，如果您在中设置了环境变量 .env 文件：

source .env
./mcp-switchbot

3.测试

# Get list of tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  SWITCHBOT_TOKEN=xxx SWITCHBOT_SECRET=yyy ./mcp-switchbot

使用Docker运行

构建

make docker-build

跑

# Set environment variables and run
export SWITCHBOT_TOKEN='your_token'
export SWITCHBOT_SECRET='your_secret'
make docker-run

或者，使用docker compose：

# Set environment variables in .env file first
docker-compose up

Kubernetes部署

1.创建秘密

kubectl create secret generic switchbot-keys \
  --from-literal=token='YOUR_TOKEN' \
  --from-literal=secret='YOUR_SECRET'

2.构建和推送图像

# Build image
docker build -t your-registry/mcp-switchbot:latest .

# Push to registry
docker push your-registry/mcp-switchbot:latest

3.编辑k8s.yaml

更新 image: 领域 k8s.yaml 使用您的注册表URL。

4.部署

kubectl apply -f k8s.yaml

5.配置克劳德桌面

~/.config/claude/claude_desktop_config.json （Linux/Mac）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "switchbot": {
      "command": "kubectl",
      "args": [
        "exec",
        "-i",
        "deployment/mcp-switchbot",
        "--",
        "/app/mcp-switchbot"
      ]
    }
  }
}

与Claude桌面的本地连接

要在没有Kubernetes的情况下直接使用本地二进制文件：

{
  "mcpServers": {
    "switchbot": {
      "command": "/path/to/mcp-switchbot",
      "env": {
        "SWITCHBOT_TOKEN": "your_token",
        "SWITCHBOT_SECRET": "your_secret"
      }
    }
  }
}

可用工具

此MCP服务器提供183个工具。主要类别：

  • 设备状态: getXxxStatus （获取每个设备的当前状态）
  • 设备控制: Xxx_turnOn/turnOff （电源开/关）
  • 参数设置: Xxx_setBrightness, Xxx_setColorTemperature等等。
  • 场景执行: executeScene （执行已注册的场景）

有关工具的完整列表，请参阅 mcp-server.yaml.

自动更新YAML规范

如果满足以下条件，服务器会自动下载最新版本 mcp-server.yaml 启动时不存在。

通过环境变量进行控制

  • MCP_YAML_URL：下载YAML规范的URL（默认：官方SwitchBot存储库）
  • MCP_FORCE_UPDATE：设置为 true 每次启动时强制下载最新版本
# Force download latest version on startup
MCP_FORCE_UPDATE=true ./mcp-switchbot

手动YAML更新

make update-yaml

发展

CI/CD管道

该项目包括使用GitHub Actions的自动化CI/CD管道：

  • 持续集成：对每个pull请求运行lint、构建、测试和安全扫描
  • 自动释放：推送标签时自动生成多平台二进制文件和Docker镜像
  • 依赖关系更新：Dependabot每周检查依赖关系

在本地运行CI检查：

make ci  # Lint + Build + Test

检查工具数量

make count-tools

更新依赖关系

make deps

贡献

对于贡献者，请参阅 贡献.md.

建筑

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ stdio (JSON-RPC)
         │
┌────────▼────────┐
│  MCP Server     │
│  (Go)           │
│                 │
│  - YAML Parser  │
│  - Tool Gen     │
│  - HMAC Auth    │
└────────┬────────┘
         │ HTTPS
         │
┌────────▼────────┐
│  SwitchBot API  │
│  v1.1           │
└─────────────────┘

关键组件

  1. YAML解析器：从加载工具定义 mcp-server.yaml
  2. 动态工具生成：在运行时生成183个工具
  3. HMAC-SHA256身份验证：为每个请求生成签名
  4. HTTP客户端：处理对SwitchBot API的请求

故障排除

Claude Desktop显示“失败”

  1. 检查调试日志:

    tail -f /tmp/mcp-switchbot-debug.log

  2. 手动测试:

    cd /Users/spm/Documents/workspace/myspace/mcp-switchbot-go
./test-mcp.sh

  3. 验证环境变量: 确保 SWITCHBOT_TOKEN 和 SWITCHBOT_SECRET 在Claude Desktop配置文件中正确设置

  4. 检查克劳德桌面日志:

    • 雨衣： ~/Library/Logs/Claude/
    • 窗户： %APPDATA%\Claude\logs\

错误：“SWITCHBOT_TOKEN和SWITCHBOT_SCRET环境变量是必需的”

未设置环境变量。将以下内容添加到您的Claude Desktop配置文件中(claude_desktop_config.json):

{
  "mcpServers": {
    "switchbot": {
      "command": "/path/to/mcp-switchbot",
      "env": {
        "SWITCHBOT_TOKEN": "your_token_here",
        "SWITCHBOT_SECRET": "your_secret_here"
      }
    }
  }
}

错误：“读取mcp服务器.yaml失败”

mcp-server.yaml 找不到文件。尝试：

  1. 通过环境变量显式指定路径:

    "env": {
  "SWITCHBOT_TOKEN": "xxx",
  "SWITCHBOT_SECRET": "yyy",
  "MCP_YAML_PATH": "/Users/spm/Documents/workspace/myspace/mcp-switchbot-go/mcp-server.yaml"
}

  2. 手动下载:

    make update-yaml

Docker stdin不工作

添加 -i 标记为 docker run:

docker run -i --rm -e SWITCHBOT_TOKEN=xxx -e SWITCHBOT_SECRET=yyy mcp-switchbot:latest

许可证

该项目在MIT许可证下发布。

相关链接

来源：

相关 MCP