apiarya/wemo-mcp-server

完整文档

uvx --version

通过 Claude Code CLI 在几秒钟内开始使用：

claude mcp add wemo -- uvx wemo-mcp-server

连接

一键安装

点击对应的客户端立即安装：

| 客户端 | 安装 |
|--------|---------|
| Claude Desktop |  |
| Claude Code CLI | 运行：claude mcp add wemo -- uvx wemo-mcp-server |
| VS Code |  |
| Cursor |  |
| Cline | 手动配置 (VS Code 扩展) |
| Windsurf | 手动配置 |
| Zed | 手动配置 |
| Continue | 手动配置 (VS Code 扩展) |

手动配置

#### Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "wemo": {
      "command": "uvx",
      "args": ["wemo-mcp-server"],
      "env": {
        "WEMO_MCP_DEFAULT_SUBNET": "192.168.1.0/24"
      }
    }
  }
}

#### VS Code

编辑 ~/.vscode/mcp.json：

{
  "servers": {
    "wemo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["wemo-mcp-server"],
      "env": {
        "WEMO_MCP_DEFAULT_SUBNET": "192.168.1.0/24"
      }
    }
  }
}

#### Cursor

编辑 ~/.cursor/mcp.json：

{
  "servers": {
    "wemo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["wemo-mcp-server"]
    }
  }
}

#### Cline

Cline 是一个 VS Code 扩展。将其添加到 VS Code 的 settings.json 中：

{
  "mcp.servers": {
    "wemo": {
      "command": "uvx",
      "args": ["wemo-mcp-server"]
    }
  }
}

#### Windsurf

编辑 ~/.windsurf/mcp.json：

{
  "mcpServers": {
    "wemo": {
      "command": "uvx",
      "args": ["wemo-mcp-server"]
    }
  }
}

#### Zed

编辑 ~/.config/zed/settings.json：

{
  "context_servers": {
    "wemo": {
      "command": "uvx",
      "args": ["wemo-mcp-server"]
    }
  }
}

#### Continue

Continue 是一个 VS Code 扩展。编辑 ~/.continue/config.json：

{
  "mcpServers": [
    {
      "name": "wemo",
      "command": "uvx",
      "args": ["wemo-mcp-server"]
    }
  ]
}

---

Configuration

WeMo MCP Server 支持通过 YAML 文件和环境变量进行灵活配置。

Quick Configuration

最重要的设置是您的 network subnet —— 服务器默认值为 192.168.1.0/24，但您的设备可能处于不同的子网（例如 192.168.86.0/24）。

在您的 MCP 客户端配置中使用 env 直接进行设置：

"env": {
  "WEMO_MCP_DEFAULT_SUBNET": "192.168.86.0/24"
}

使用环境变量（最简单）：

export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_CACHE_TTL=7200
export WEMO_MCP_LOG_LEVEL=DEBUG

# Copy example config and customize
cp config.example.yaml config.yaml
Edit config.yaml with your settings

| 设置 | 环境变量 | 默认值 | 描述 |
|---------|---------------------|---------|-------------|
| Network ||||
| 默认子网 | WEMO_MCP_DEFAULT_SUBNET | 192.168.1.0/24 | 用于扫描设备的网络 |
| 扫描超时 | WEMO_MCP_SCAN_TIMEOUT | 0.6 | 端口探测超时（秒） |
| 最大工作线程 | WEMO_MCP_MAX_WORKERS | 60 | 并发扫描线程数 |
| Cache ||||
| 启用缓存 | WEMO_MCP_CACHE_ENABLED | true | 持久化设备缓存 |
| 缓存文件 | WEMO_MCP_CACHE_FILE | ~/.wemo_mcp_cache.json | 缓存文件路径 |
| 缓存 TTL | WEMO_MCP_CACHE_TTL | 3600 | 缓存有效期（秒） |
| Logging ||||
| 日志级别 | WEMO_MCP_LOG_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR |

配置示例

大型网络（多个子网）：

export WEMO_MCP_DEFAULT_SUBNET="10.0.0.0/16"
export WEMO_MCP_SCAN_TIMEOUT=1.0
export WEMO_MCP_MAX_WORKERS=100

export WEMO_MCP_LOG_LEVEL=DEBUG
export WEMO_MCP_CACHE_TTL=300  # 5 minutes

export WEMO_MCP_CACHE_ENABLED=false

有关详细的配置指南，请参阅 CONFIGURATION.md。

---

MCP Tools

1. scan_network

使用智能多阶段扫描在网络中发现 WeMo 设备。

Example Prompts:

• "Scan for WeMo devices on my network"

• "Find all WeMo devices"

• "Discover devices on 192.168.1.0/24"

Example Response:

Found 12 WeMo devices in 23.5 seconds:

1. Office Light (Dimmer) - 192.168.1.100 - OFF
2. Living Room (Switch) - 192.168.1.101 - ON
3. Bedroom Lamp (Dimmer) - 192.168.1.102 - OFF
...

列出所有从之前扫描中缓存的设备。

示例提示词：

• "List all my WeMo devices"

• "Show me all devices"

• "What devices do you know about?"

示例响应：

12 devices in cache:

Office Light (Dimmer) at 192.168.1.100
Living Room (Switch) at 192.168.1.101
Bedroom Lamp (Dimmer) at 192.168.1.102
...

获取特定设备的当前状态和信息。

示例提示词：

• "办公室的灯开了吗？"

• "卧室灯的状态是什么？"

• "检查客厅开关"

• "办公室灯的亮度是多少？"

示例响应：

Office Light (Dimmer):
State: OFF

Brightness: 75%

IP: 192.168.1.100

Model: DimmerLongPress

控制 WeMo 设备（开启/关闭/切换/亮度）。

示例提示词：

• "Turn on the office light"

• "Turn off the living room"

• "Toggle the bedroom lamp"

• "Set office light to 75%"

• "Dim the bedroom lamp to 50%"

示例响应：

✓ Office Light turned ON
  Brightness set to 75%
  Current state: ON

重命名 WeMo 设备（更改其友好名称）。

示例提示词：

• "Rename Office Dimmer to Office Light"

• "Change the name of the bedroom device to Bedroom Lamp"

• "Call the living room switch 'Main Light'"

示例响应：

✓ Device renamed successfully
  'Office Dimmer' → 'Office Light'
  IP: 192.168.1.100

The new name will appear in the WeMo app and all control interfaces.

获取 WeMo 设备的 HomeKit 设置代码。

示例提示词：

• "Get the HomeKit code for Office Light"

• "What's the HomeKit setup code for the bedroom lamp?"

• "Show me the HomeKit code for all devices"

示例响应：

HomeKit Setup Code for 'Office Light':
  123-45-678

Use this code to add the device to Apple Home.

!HomeKit code retrieval step 1

!HomeKit code retrieval step 2

7. get_cache_info

获取关于持久化设备缓存的信息。

示例提示词：

• "Show me cache information"

• "Is the device cache expired?"

• "How many devices are cached?"

示例响应：

Device Cache Status:
  ✅ Cache exists
  📁 Location: ~/.wemo_mcp_cache.json
  📊 Devices: 12
  ⏰ Age: 1,234 seconds (20.6 minutes)
  💾 TTL: 3,600 seconds (1 hour)
  ✅ Status: Valid (not expired)

清除持久化设备缓存以强制重新扫描。

示例提示词：

• "Clear the device cache"

• "Reset the cache and rescan"

• "Delete cached devices"

示例响应：

✅ Cache cleared successfully
Next scan will discover devices fresh.
Run scan_network to rebuild the cache.

9. get_configuration

查看当前服务器配置设置。

示例提示词：

• "Show me the server configuration"

• "What are the current settings?"

• "Display configuration"

示例响应：

Current Configuration:
  Network:
    • Default subnet: 192.168.1.0/24
    • Scan timeout: 0.6 seconds
    • Max workers: 60
  Cache:
    • Enabled: true
    • File: ~/.wemo_mcp_cache.json
    • TTL: 3600 seconds (1 hour)
  Logging:
    • Level: INFO

---

MCP Capabilities

除了 tools，该服务器还提供了完整的 MCP primitives。

Resources

无需调用 tool 即可订阅实时设备数据：

| URI | Description |
|-----|-------------|
| devices:// | 所有缓存设备的 JSON 索引 |
| device://{name-or-ip} | 特定设备的实时状态（支持 URL 编码的名称） |

支持 MCP Resources 的客户端（如 VS Code, MCP Inspector）可以直接读取这些内容。

Prompts

在支持的客户端中，可通过 / 斜杠命令使用四个内置的引导式 prompts：

| Prompt | Description |
|--------|-------------|
| discover-devices | 带有子网选择的引导式网络扫描 |
| device-status-report | 所有设备状态的汇总报告 |
| activate-scene | 将多个设备作为场景进行控制 |
| troubleshoot-device | 分步设备故障排除 |

!MCP prompts in VS Code

*这四个 prompts 在 VS Code 中均以 /mcp.wemo.* 斜杠命令的形式呈现*

Elicitations

服务器会主动请求缺失的信息，而不是静默失败：- scan_network — 如果未配置自定义子网（默认 192.168.1.0/24），在继续之前会询问要扫描哪个子网

• control_device — 如果在缓存中未找到设备名称，会显示最接近的匹配项并询问目标设备

!MCP elicitation prompting for subnet

*Elicitation 实际运行效果 — 服务器请求子网信息，而不是静默地扫描错误的网络*

Client Support Matrix

| Feature | Claude Desktop | VS Code | Cursor | MCP Inspector |
|---------|:--------------:|:-------:|:------:|:-------------:|
| Tools | ✅ | ✅ | ✅ | ✅ |
| Resources | ⚠️ 仅协议支持 | ✅ | ✅ | ✅ |
| Prompts | ⚠️ 无 slash UI | ✅ / 命令 | ✅ | ✅ |
| Elicitations | ✅ v1.1+ | ❌ | ❌ | ✅ v0.20+ |

---

How It Works

Multi-Phase Discovery

服务器采用一个经过可靠性优化的三阶段发现流程：

1. Phase 1 - UPnP/SSDP Discovery (Primary)
- 通过组播发现所有有响应的设备（约 12s）
- 最可靠的方法，可发现不对端口探测做出响应的设备
- 使用 pywemo 内置的发现机制

2. Phase 2 - Network Port Scanning (Backup)
- 在子网内并行探测 WeMo 端口 (49152-49155)
- 采用 60 个并发 worker 进行快速扫描（254 个 IP 约 10s）
- 捕捉被 UPnP 遗漏的设备3. 阶段 3 - 设备验证 (备份)
- 通过 /setup.xml 对活跃 IP 进行 HTTP 验证
- 使用 60 个 worker 进行并行验证
- 验证并提取设备信息

该方法在保持快速扫描时间（完整网络仅需 23-30 秒）的同时，实现了 100% 的设备发现可靠性。

本地控制信号流

所有设备命令仅在您的 local network 中传输 —— 任何阶段都无需经过云端跳转。

语音路径 (Google Home + WeMo)：

sequenceDiagram
    participant U as User
    participant GH as Google Home Hub
    participant GC as Google Cloud (ASR only)
    participant WD as WeMo Device

U->>GH: "Hey Google, turn on chandelier"
    GH->>GC: Audio stream for speech-to-text
    GC-->>GH: Intent: {action: ON, device: chandelier}
    GH->>WD: Matter OnOff.On (UDP 5540, LAN)
    WD-->>GH: ACK
    GH-->>U: "OK, turning on chandelier"

sequenceDiagram
    participant U as User
    participant AI as AI Assistant
    participant MS as MCP Server
    participant WD as WeMo Device

U->>AI: "Turn on the desk light"
    AI->>MS: tools/call control_device("desk light", "on")
    MS->>WD: UPnP/SOAP BinaryState=1 (TCP 49153, LAN)
    WD-->>MS: HTTP 200 OK
    MS-->>AI: {success: true, state: "on"}
    AI-->>U: "Desk light is now on!"

功能对比

MCP Server vs wemo-ops-center

本 MCP server 与主项目 wemo-ops-center 的功能对比：

| 功能 | wemo-ops-center | MCP Server | 备注 |
|---------|-----------------|------------|-------|
| 设备发现 | ✅ UPnP + Port Scan | ✅ 已实现 | 多阶段发现，100% 可靠性 |
| 设备控制 | ✅ On/Off/Toggle | ✅ 已实现 | 包含对 dimmers 的亮度控制 |
| 设备状态 | ✅ 实时 | ✅ 已实现 | 通过名称或 IP 地址查询 |
| 设备重命名 | ✅ Friendly names | ✅ 已实现 | 自动更新设备缓存 |
| HomeKit 代码 | ✅ 提取代码 | ✅ 已实现 | 适用于 HomeKit 兼容设备 |
| 多子网 | ✅ VLAN 支持 | ❌ 计划中 | 目前每次扫描仅限单个子网 |
| WiFi 配置 | ✅ Smart setup | ❌ 未计划 | 需要更改 PC WiFi 连接 |
| 定时任务 | ✅ 时间 + 太阳 | ❌ 未计划 | 需要持久化 daemon（与 MCP 模型不兼容） |
| 维护工具 | ✅ 重置 | ❌ 未计划 | 恢复出厂设置、清除 WiFi、清除数据 |
| 配置文件管理 | ✅ 保存/加载 | ❌ 未计划 | 用于批量设置的 WiFi 凭据配置文件 |
| 用户界面 | ✅ GUI + Web | ❌ 不适用 | MCP 使用 AI 助手界面 |图例：

• ✅ 已实现 - 功能可用

• ❌ 未计划 - 功能与 MCP 架构或用例冲突

• ❌ 计划中 - 功能可在未来添加

为什么某些功能未在 MCP 中计划：

• Scheduling：需要 24/7 后台守护进程轮询。MCP servers 通常由 AI assistants 按需调用，而非作为持久服务运行。

• WiFi Provisioning：需要将主机 PC 的 WiFi 连接更改为设备设置网络，这具有破坏性且依赖于具体平台。

• Maintenance Tools：破坏性操作（如 factory reset 等）更适合带有确认对话框的专用 GUI。

当前 MCP 覆盖率： 11 项核心功能中的 5 项 (45%) - 专注于符合 MCP 模型的设备发现、监控和控制用例。

Development

Setup

bash

git clone https://github.com/apiarya/wemo-mcp-server.git