wemo

WeMo MCP 服务

通过自然语言，使用 AI 助手控制 WeMo 智能家居设备。

mcp-name: io.github.apiarya/wemo

目录

• 概述
• 先决条件
• 快速开始
• 连接
• 配置
• MCP 工具
  • scan_network
  • list_devices
  • get_device_status
  • control_device
  • rename_device
  • get_homekit_code
  • get_cache_info
  • clear_cache
  • get_configuration
• MCP 能力
  • 资源
  • 提示词
  • 征询
• 工作原理
  • 本地控制信号流
• 功能对比
• 开发
• 贡献
• 许可证
• 致谢

概述

通过 Model Context Protocol，将 WeMo 智能家居设备与 AI 助手无缝集成。此服务基于 pywemo 构建，支持以自然语言控制 WeMo 设备，并具备智能多阶段发现功能。

使用示例

通过自然语言，使用 AI 助手控制 WeMo 设备——只需用通俗的英语提出要求！

“晚安”——一条指令即可关闭家中所有设备

主要功能

• 🔍 智能发现 - 多阶段扫描（UPnP/SSDP + 网络端口），可靠性达 100%
• ⚡ 快速扫描 - 使用 60 个并发工作线程进行并行探测（扫描整个子网约需 23-30 秒）
• 🎛️ 全面控制 - 控制所有设备类型的开/关、切换和亮度
• ✏️ 设备管理 - 重命名设备并提取 HomeKit 设置代码
• 📊 实时状态 - 查询设备状态和亮度
• 💾 智能缓存 - 持久化设备缓存，TTL 为 1 小时，重启后仍然有效
• 🔧 可配置 - 使用 YAML 配置文件和环境变量设置所有选项
• 🔄 自动重试 - 遇到网络错误时自动以指数退避方式重试
• 🛡️ 错误处理 - 提供详细错误消息和可操作的建议
• 🔌 通用兼容 - 适用于任何 MCP 客户端（Claude、VS Code、Cursor 等）
• 📡 MCP 资源 - 通过 devices:// 和 device://{id} URI 获取实时设备状态
• 💬 MCP 提示词 - 内置引导式提示词：发现设备、状态报告、场景控制、故障排查
• 🗣️ MCP 引导请求 - 当子网或设备名称不明确时进行交互式澄清

---

前置条件

所有配置均使用 uvx（来自 uv Python 包管理器）运行服务。请先安装 uv：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS with Homebrew
brew install uv

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后，重启终端并验证：

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

保存后重启 Claude Desktop。

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

保存后重新加载 VS Code。

Cursor

编辑 ~/.cursor/mcp.json：

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

保存后重启 Cursor。

Cline

Cline 是一个 VS Code 扩展。将以下内容添加到 VS Code 的 settings.json：

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

保存后重新加载 VS Code。

Windsurf

编辑 ~/.windsurf/mcp.json：

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

保存后重启 Windsurf。

Zed

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

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

保存后重启 Zed。

Continue

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

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

保存后重新加载 VS Code。

---

配置

WeMo MCP 服务支持通过 YAML 文件和环境变量灵活配置。

快速配置

最重要的设置是你的网络子网——服务默认使用 192.168.1.0/24，但你的设备可能位于其他子网（例如 192.168.86.0/24）。

使用 env 在 MCP 客户端配置中直接设置：

"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

使用 YAML 配置文件：

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

配置选项

设置	环境变量	默认值	描述
网络
默认子网	WEMO_MCP_DEFAULT_SUBNET	192.168.1.0/24	扫描设备的网络
扫描超时	WEMO_MCP_SCAN_TIMEOUT	0.6	端口探测超时时间（秒）
最大工作线程数	WEMO_MCP_MAX_WORKERS	60	并发扫描线程数
缓存
启用缓存	WEMO_MCP_CACHE_ENABLED	true	持久化设备缓存
缓存文件	WEMO_MCP_CACHE_FILE	~/.wemo_mcp_cache.json	缓存文件位置
缓存 TTL	WEMO_MCP_CACHE_TTL	3600	缓存有效期（秒）
日志
日志级别	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

完整配置模板请参阅 config.example.yaml 和 .env.example。

详细配置指南请参阅 CONFIGURATION.md。

---

MCP 工具

1. scan_network

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

提示词示例：

• “扫描网络中的 WeMo 设备”
• “查找所有 WeMo 设备”
• “发现 192.168.1.0/24 上的设备”

响应示例：

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

2. list_devices

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

提示词示例：

• “列出我的所有 WeMo 设备”
• “显示所有设备”
• “你知道哪些设备？”

响应示例：

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

3. get_device_status

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

提示词示例：

• “办公室的灯开着吗？”
• “卧室台灯的状态是什么？”
• “检查一下客厅的开关”
• “办公室灯的亮度是多少？”

响应示例：

Office Light (Dimmer):
- State: OFF
- Brightness: 75%
- IP: 192.168.1.100
- Model: DimmerLongPress

4. control_device

控制 WeMo 设备（开／关／切换／亮度）。

提示词示例：

• “打开办公室的灯”
• “关闭客厅的灯”
• “切换卧室台灯的状态”
• “将办公室灯设置为 75%”
• “将卧室台灯调暗至 50%”

响应示例：

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

5. rename_device

重命名 WeMo 设备（更改其易记名称）。

提示词示例：

• “将 Office Dimmer 重命名为 Office Light”
• “将卧室设备的名称改为 Bedroom Lamp”
• “把客厅开关命名为 ‘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.

6. get_homekit_code

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

提示词示例：

• “获取 Office Light 的 HomeKit 代码”
• “卧室台灯的 HomeKit 设置代码是什么？”
• “显示所有设备的 HomeKit 代码”

响应示例：

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

Use this code to add the device to Apple Home.

**注意：**并非所有 WeMo 设备都支持 HomeKit。如果设备不支持 HomeKit，你会收到错误消息。

7. get_cache_info

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

提示词示例：

• “显示缓存信息”
• “设备缓存过期了吗？”
• “缓存了多少台设备？”

响应示例：

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)

8. clear_cache

清除持久化设备缓存，以便强制执行全新扫描。

提示词示例：

• “清除设备缓存”
• “重置缓存并重新扫描”
• “删除缓存的设备”

响应示例：

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

**注意：**此操作会同时清除持久化缓存文件和内存缓存。清除后，运行 scan_network 以重新发现设备。

9. get_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

**注意：**显示所有配置，包括默认值和环境变量覆盖值。使用带有 WEMO_MCP_ 前缀的环境变量进行自定义。

---

MCP 功能

除了工具，此服务还提供完整的 MCP 原语套件。

资源

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

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

支持 MCP 资源的客户端（VS Code、MCP Inspector）可以直接读取这些资源。

提示词

支持的客户端中可通过 / 斜杠命令使用四个内置引导提示词：

提示词	描述
discover-devices	通过选择子网引导网络扫描
device-status-report	所有设备状态的摘要报告
activate-scene	将多个设备作为一个场景进行控制
troubleshoot-device	逐步排查设备问题

VS Code 中以 /mcp.wemo.* 斜杠命令形式呈现的全部四个提示词

信息征询

如果缺少信息，服务会主动询问，而不是静默失败：

• scan_network — 如果未配置自定义子网（默认值为 192.168.1.0/24），会在继续之前询问要扫描哪个子网
• control_device — 如果缓存中找不到设备名称，会显示最接近的匹配项，并询问指的是哪个设备

信息征询示例 — 服务会询问子网，而不是静默扫描错误的网络

客户端支持矩阵

功能	Claude Desktop	VS Code	Cursor	MCP Inspector
工具	✅	✅	✅	✅
资源	⚠️ 仅协议支持	✅	✅	✅
提示词	⚠️ 无斜杠命令界面	✅ / 命令	✅	✅
信息征询	✅ v1.1+	❌	❌	✅ v0.20+

---

工作原理

多阶段发现

服务采用三阶段发现流程，以提升可靠性：

1. 阶段 1 - UPnP/SSDP 发现（主要方式）

   • 通过多播发现所有响应设备（约 12 秒）
   • 最可靠的方法，可发现不响应端口探测的设备
   • 使用 pywemo 内置的发现机制

2. 阶段 2 - 网络端口扫描（备用方式）

   • 在子网范围内并行探测 WeMo 端口（49152-49155）
   • 使用 60 个并发工作线程快速扫描（扫描 254 个 IP 约需 10 秒）
   • 捕获 UPnP 未发现的设备

3. 阶段 3 - 设备验证（备用方式）

   • 通过 /setup.xml 对活跃 IP 进行 HTTP 验证
   • 使用 60 个工作线程并行验证
   • 验证并提取设备信息

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

本地控制信号流

所有设备命令都只通过你的本地网络传输——任何阶段都不需要经过云端。

语音路径（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"

MCP 路径（AI 助手 + 此服务）：

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

两种路径在初始语音识别后都只使用本地协议（Google Cloud 负责语音转文字；Belkin 的云端从不参与）。

功能对比

MCP 服务与 wemo-ops-center

此 MCP 服务与主项目 wemo-ops-center 的功能对比：

功能	wemo-ops-center	MCP 服务	说明
设备发现	✅ UPnP + 端口扫描	✅ 已实现	多阶段发现，可靠性达 100%
设备控制	✅ 开/关/切换	✅ 已实现	包含调光器的亮度控制
设备状态	✅ 实时	✅ 已实现	可按名称或 IP 地址查询
设备重命名	✅ 友好名称	✅ 已实现	自动更新设备缓存
HomeKit 代码	✅ 提取代码	✅ 已实现	适用于兼容 HomeKit 的设备
多子网	✅ VLAN 支持	❌ 计划中	目前每次扫描仅支持单个子网
WiFi 配网	✅ 智能设置	❌ 不计划实现	需要更改 PC 的 WiFi 连接
计划任务	✅ 时间 + 太阳能	❌ 不计划实现	需要持久运行的守护进程（与 MCP 模型不兼容）
维护工具	✅ 重置	❌ 不计划实现	恢复出厂设置、清除 WiFi、清除数据
配置文件管理	✅ 保存/加载	❌ 不计划实现	用于批量设置的 WiFi 凭据配置文件
用户界面	✅ GUI + Web	❌ 不适用	MCP 使用 AI 助手界面

图例：

• ✅ 已实现 - 功能可用
• ❌ 不计划实现 - 功能与 MCP 架构或使用场景冲突
• ❌ 计划中 - 未来可能添加此功能

部分功能不计划在 MCP 中实现的原因：

• 计划任务：需要每周 7 天、每天 24 小时运行后台守护进程进行轮询。MCP 服务通常由 AI 助手按需调用，而非作为持久服务运行。
• WiFi 配网：需要将主机 PC 的 WiFi 连接切换到设备设置网络，这会造成干扰，并且因平台而异。
• 维护工具：破坏性操作（如恢复出厂设置等）更适合通过带确认对话框的专用 GUI 执行。

当前 MCP 覆盖率： 11 项核心功能中的 5 项（45%）——专注于适合 MCP 模型的设备发现、监控和控制场景。

开发

设置

git clone https://github.com/apiarya/wemo-mcp-server.git
cd wemo-mcp-server
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --dev

运行测试

# Unit tests (CI-compatible, ~4 seconds, 128 tests)
.venv/bin/python -m pytest tests/test_server.py tests/test_phase2.py tests/test_models.py -v

# With coverage report
pytest tests/test_server.py tests/test_phase2.py tests/test_models.py --cov=wemo_mcp_server --cov-report=html

# E2E tests (requires WeMo devices on network)
python tests/test_e2e.py

使用开发版本

在 MCP 客户端配置中使用：

{
  "command": "python",
  "args": ["-m", "wemo_mcp_server"],
  "env": {
    "PYTHONPATH": "/path/to/mcp/src"
  }
}

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 添加测试并进行更改
4. 运行测试套件（python tests/test_e2e.py）
5. 提交更改（git commit -m 'Add amazing feature'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 创建 Pull Request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 基于 Model Context Protocol SDK 构建
• 使用 pywemo 与 WeMo 设备通信
• 与 wemo-ops-center 项目相关（桌面和服务端应用程序）