内容
# WeMo MCP 服务器
通过使用自然语言控制智能家居设备与 AI 助手无缝集成。
**mcp-name: io.github.apiarya/wemo**
[](https://github.com/apiarya/wemo-mcp-server/actions/workflows/ci.yml)
[](https://codecov.io/gh/apiarya/wemo-mcp-server)
[](https://sonarcloud.io/project/overview?id=apiarya_wemo-mcp-server)
[](https://sonarcloud.io/project/overview?id=apiarya_wemo-mcp-server)
[](https://pypi.org/project/wemo-mcp-server/)
[](https://www.python.org/downloads/)
[](https://registry.modelcontextprotocol.io/?q=apiarya/wemo)
[](https://modelcontextprotocol.io)
[](https://modelcontextprotocol.io/docs/concepts/transports)
[](https://opensource.org/licenses/MIT)
## 目录
- [概述](#概述)
- [前提条件](#前提条件)
- [快速开始](#快速开始)
- [连接](#连接)
- [配置](#配置)
- [MCP 工具](#mcp-工具)
- [扫描网络](#1-扫描网络)
- [列出设备](#2-列出设备)
- [获取设备状态](#3-获取设备状态)
- [控制设备](#4-控制设备)
- [重命名设备](#5-重命名设备)
- [获取 HomeKit 代码](#6-获取-homekit-代码)
- [获取缓存信息](#7-获取缓存信息)
- [清除缓存](#8-清除缓存)
- [获取配置](#9-获取配置)
- [MCP 功能](#mcp-功能)
- [资源](#资源)
- [提示](#提示)
- [诱导](#诱导)
- [工作原理](#工作原理)
- [本地控制信号流](#本地控制信号流)
- [功能比较](#功能比较)
- [开发](#开发)
- [贡献](#贡献)
- [许可证](#许可证)
- [致谢](#致谢)
## 概述
通过 Model Context Protocol 将 WeMo 智能家居设备与 AI 助手无缝集成。基于 [pywemo](https://github.com/pywemo/pywemo) 构建，该服务器使您能够使用自然语言控制 WeMo 设备，并具有智能的多阶段发现功能。
### 示例用法
*使用自然语言控制 WeMo 设备 - 只需用普通英语询问！*
*"晚安" - 一个命令关闭房子里的所有设备*
### 主要功能
- **🔍 智能发现** - 多阶段扫描（UPnP/SSDP + 网络端口）具有 100% 的可靠性
- **⚡ 快速扫描** - 并行探测具有 60 个并发工作线程（~23-30 秒完成整个子网）
- **🎛️ 全面控制** - 所有设备类型的开关/调光控制
- **✏️ 设备管理** - 重命名设备并提取 HomeKit 设置代码
- **📊 实时状态** - 查询设备状态和亮度
- **💾 智能缓存** - 具有 1 小时 TTL 的持久设备缓存
- **🔧 可配置** - YAML 配置文件 + 环境变量用于所有设置
- **🔄 自动重试** - 网络错误时的自动重试
- **🛡️ 错误处理** - 详细的错误消息和可行的建议
- **🔌 通用** - 与任何 MCP 客户端（Claude，VS Code，Cursor 等）配合使用
- **📡 MCP 资源** - 通过 `devices://` 和 `device://{id}` URI 获取实时设备状态
- **💬 MCP 提示** - 内置引导提示：发现，状态报告，场景控制，故障排除
- **🗣️ MCP 诱导** - 在子网或设备名称不明确时的交互式澄清
---
## 前提条件
所有配置都使用 `uvx`（来自 `uv` Python 包管理器）运行服务器。首先安装 [uv](https://docs.astral.sh/uv/)：
```bash
# 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"
```
安装后，重启终端并验证：
```bash
uvx --version
```
## 快速开始
使用 Claude Code CLI 快速开始：
```bash
claude mcp add wemo -- uvx wemo-mcp-server
```
---
## 连接
### 一键安装
点击您的客户端即可一键安装：
| 客户端 | 安装 |
|--------|---------|
| **Claude Desktop** | [](https://modelcontextprotocol.io/quickstart/user) |
| **Claude Code CLI** | 运行：`claude mcp add wemo -- uvx wemo-mcp-server` |
| **VS Code** | [](https://vscode.dev/redirect/mcp/install?name=wemo&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22wemo-mcp-server%22%5D%7D) |
| **Cursor** | [](cursor://anysphere.cursor-deeplink/mcp/install?name=wemo&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ3ZW1vLW1jcC1zZXJ2ZXIiXX0%3D) |
| **Cline** | [手动配置](#cline)（VS Code 扩展）|
| **Windsurf** | [手动配置](#windsurf) |
| **Zed** | [手动配置](#zed) |
| **Continue** | [手动配置](#continue)（VS Code 扩展）|
### 手动配置
#### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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`:
```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`:
```json
{
"servers": {
"wemo": {
"type": "stdio",
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
保存后重启 Cursor。
#### Cline
Cline 是 VS Code 扩展。添加到 VS Code 的 `settings.json`:
```json
{
"mcp.servers": {
"wemo": {
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
保存后重新加载 VS Code。
#### Windsurf
编辑 `~/.windsurf/mcp.json`:
```json
{
"mcpServers": {
"wemo": {
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
保存后重启 Windsurf。
#### Zed
编辑 `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"wemo": {
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
保存后重启 Zed。
#### Continue
Continue 是 VS Code 扩展。编辑 `~/.continue/config.json`:
```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`）。
直接在 MCP 客户端配置中使用 `env` 设置：
```json
"env": {
"WEMO_MCP_DEFAULT_SUBNET": "192.168.86.0/24"
}
```
或在启动服务器之前导出：
**使用环境变量**（最简单）：
```bash
export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_CACHE_TTL=7200
export WEMO_MCP_LOG_LEVEL=DEBUG
```
**使用 YAML 配置文件**：
```bash
# 复制示例配置并自定义
cp config.example.yaml config.yaml
# 使用您的设置编辑 config.yaml
```
### 配置选项
| 设置 | 环境变量 | 默认值 | 描述 |
|---------|---------------------|---------|-------------|
| **网络** ||||
| 默认子网 | `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 |
### 示例配置
**大型网络**（多个子网）：
```bash
export WEMO_MCP_DEFAULT_SUBNET="10.0.0.0/16"
export WEMO_MCP_SCAN_TIMEOUT=1.0
export WEMO_MCP_MAX_WORKERS=100
```
**调试模式**：
```bash
export WEMO_MCP_LOG_LEVEL=DEBUG
export WEMO_MCP_CACHE_TTL=300 # 5 分钟
```
**禁用缓存**：
```bash
export WEMO_MCP_CACHE_ENABLED=false
```
查看 [config.example.yaml](config.example.yaml) 和 [.env.example](.env.example) 以获取完整的配置模板。
有关详细配置指南，请参阅 [CONFIGURATION.md](CONFIGURATION.md)。
---
## MCP 工具
### 1. 扫描网络
使用智能多阶段扫描发现网络上的 WeMo 设备。
**示例提示：**
- "扫描网络上的 WeMo 设备"
- "查找所有 WeMo 设备"
- "在 192.168.1.0/24 上发现设备"
**示例响应：```
在 23.5 秒内找到 12 个 WeMo 设备：
1. 办公室灯（调光器）- 192.168.1.100 - 关闭
2. 客厅（开关）- 192.168.1.101 - 开启
3. 卧室灯（调光器）- 192.168.1.102 - 关闭
...
```
### 2. 列出设备
列出从以前扫描缓存的所有设备。
**示例提示：**
- "列出所有我的 WeMo 设备"
- "显示所有设备"
- "你知道哪些设备？"
**示例响应：```
缓存中有 12 个设备：
- 办公室灯（调光器）位于 192.168.1.100
- 客厅（开关）位于 192.168.1.101
- 卧室灯（调光器）位于 192.168.1.102
...
```
### 3. 获取设备状态
获取特定设备的当前状态和信息。
**示例提示：**
- "办公室灯是否开启？"
- "卧室灯的状态是什么？"
- "检查客厅开关"
- "办公室灯的亮度是多少？"
**示例响应：```
办公室灯（调光器）：
- 状态：关闭
- 亮度：75%
- IP：192.168.1.100
- 型号：DimmerLongPress
```
### 4. 控制设备
控制 WeMo 设备（开关/调光）。
**示例提示：**
- "打开办公室灯"
- "关闭客厅"
- "切换卧室灯"
- "将办公室灯设置为 75%"
- "将卧室灯调暗到 50%"
**示例响应：```
✓ 办公室灯已开启
亮度设置为 75%
当前状态：开启
```
### 5. 重命名设备
重命名 WeMo 设备（更改其友好名称）。
**示例提示：**
- "将办公室调光器重命名为办公室灯"
- "将卧室设备名称更改为卧室灯"
- "将客厅开关称为'主灯'"
**示例响应：```
✓ 设备成功重命名
'办公室调光器' → '办公室灯'
IP：192.168.1.100
新名称将出现在 WeMo 应用程序和所有控制界面中。
### 6. 获取 HomeKit 代码
获取 WeMo 设备的 HomeKit 设置代码。
**示例提示：**
- "获取办公室灯的 HomeKit 代码"
- "卧室灯的 HomeKit 设置代码是什么？"
- "显示所有设备的 HomeKit 代码"
**示例响应：```
办公室灯的 HomeKit 设置代码：
123-45-678
使用此代码将设备添加到 Apple Home。
```
**注意：** 并非所有 WeMo 设备都支持 HomeKit。如果设备不支持 HomeKit，您将收到错误消息。
### 7. 获取缓存信息
获取持久设备缓存的信息。
**示例提示：**
- "显示缓存信息"
- "设备缓存是否过期？"
- "缓存了多少台设备？"
**示例响应：```
设备缓存状态：
✅ 缓存存在
📁 位置：~/.wemo_mcp_cache.json
📊 设备：12
⏰ 年龄：1234 秒（20.6 分钟）
💾 TTL：3600 秒（1 小时）
✅ 状态：有效（未过期）
```
### 8. 清除缓存
清除持久设备缓存以强制进行新的扫描。
**示例提示：**
- "清除设备缓存"
- "重置缓存并重新扫描"
- "删除缓存设备"
**示例响应：```
✅ 缓存清除成功
下次扫描将重新发现设备。
运行 scan_network 以重建缓存。
```
**注意：** 这将清除持久缓存文件和内存缓存。清除后，运行 `scan_network` 以重新发现设备。
### 9. 获取配置
查看当前的服务器配置设置。
**示例提示：**
- "显示服务器配置"
- "当前设置是什么？"
- "显示配置"
**示例响应：```
当前配置：
网络：
• 默认子网：192.168.1.0/24
• 扫描超时：0.6 秒
• 最大工作线程：60
缓存：
• 已启用：true
• 文件：~/.wemo_mcp_cache.json
• TTL：3600 秒（1 小时）
日志记录：
• 级别：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`** - 如果设备名称不在缓存中，呈现最接近的匹配项并询问要控制的设备
*MCP 诱导提示 - 服务器询问子网而不是静默扫描错误网络*
### 客户端支持矩阵
| 功能 | Claude Desktop | VS Code | Cursor | MCP Inspector |
|---------|:--------------:|:-------:|:------:|:-------------:|
| 工具 | ✅ | ✅ | ✅ | ✅ |
| 资源 | ⚠️ 仅限协议 | ✅ | ✅ | ✅ |
| 提示 | ⚠️ 没有斜杠 UI | ✅ `/` 命令 | ✅ | ✅ |
| 诱导 | ✅ v1.1+ | ❌ | ❌ | ✅ v0.20+ |
---
## 工作原理
### 多阶段发现
服务器使用三阶段发现过程，优化了可靠性：
1. **第一阶段 - UPnP/SSDP 发现（主要）**
- 多播发现找到所有响应设备（~12 秒）
- 最可靠的方法，找到不响应端口探测的设备
- 使用 pywemo 内置的发现机制
2. **第二阶段 - 网络端口扫描（备份）**
- 子网内 WeMo 端口（49152-49155）的并行探测
- 60 个并发工作线程用于快速扫描（~10 秒完成 254 个 IP 地址）
- 捕获 UPnP 遗漏的设备
3. **第三阶段 - 设备验证（备份）**
- 通过 /setup.xml 验证活动 IP 地址
- 60 个工作线程并行验证
- 验证并提取设备信息
这种方法实现了 **100% 设备发现可靠性**，同时保持快速扫描时间（23-30 秒完成整个网络）。
---
## 功能比较
---
## 开发
---
## 贡献
---
## 许可证
---
## 致谢
---
### 本地控制信号流程
所有设备命令都仅通过您的 **本地网络** 进行传输 — 在任何阶段都不需要云端中转。
**语音路径（Google Home + WeMo）：**
```mermaid
sequenceDiagram
participant U as 用户
participant GH as Google Home Hub
participant GC as Google Cloud（仅限语音转文本）
participant WD as WeMo 设备
U->>GH: "嘿 Google，打开吊灯"
GH->>GC: 语音流用于语音转文本
GC-->>GH: 意图：{操作：打开，设备：吊灯}
GH->>WD: Matter OnOff.On（UDP 5540，局域网）
WD-->>GH: 确认
GH-->>U: "好的，正在打开吊灯"
```
**MCP 路径（AI 助手 + 此服务器）：**
```mermaid
sequenceDiagram
participant U as 用户
participant AI as AI 助手
participant MS as MCP 服务器
participant WD as WeMo 设备
U->>AI: "打开台灯"
AI->>MS: 工具/调用 control_device("台灯", "打开")
MS->>WD: UPnP/SOAP BinaryState=1（TCP 49153，局域网）
WD-->>MS: HTTP 200 确认
MS-->>AI: {成功：true，状态： "打开"}
AI-->>U: "台灯现在已打开！"
```
两条路径在初始语音识别后都使用 **仅本地协议** （Google Cloud 处理语音转文本；Belkin 的云端服务从未涉及）。
## 功能比较
### MCP 服务器 vs. wemo-ops-center
比较此 MCP 服务器与主要 [wemo-ops-center](https://github.com/qrussell/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 中实现的原因：**
- **调度**：需要 24/7 的后台守护进程轮询。MCP 服务器通常由 AI 助手按需调用，而不是作为持久服务运行。
- **WiFi 配置**：需要更改主机 PC 的 WiFi 连接到设备设置网络，这会造成干扰并且特定于平台。
- **维护工具**：破坏性操作（例如，工厂重置）更适合具有确认对话框的专用 GUI。
**当前 MCP 覆盖率：** 5/11 个核心功能（45%）- 关注于设备发现、监控和控制用例，这些用例适合 MCP 模型。
## 开发
### 设置
```bash
git clone https://github.com/apiarya/wemo-mcp-server.git
cd wemo-mcp-server
uv venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
uv sync --dev
```
### 运行测试
```bash
# 单元测试（与 CI 兼容，~4 秒，128 个测试）
.venv/bin/python -m pytest tests/test_server.py tests/test_phase2.py tests/test_models.py -v
# 带有覆盖率报告
pytest tests/test_server.py tests/test_phase2.py tests/test_models.py --cov=wemo_mcp_server --cov-report=html
# 端到端测试（需要网络上的 WeMo 设备）
python tests/test_e2e.py
```
### 使用开发版本
在您的 MCP 客户端配置文件中，使用：
```json
{
"command": "python",
"args": ["-m", "wemo_mcp_server"],
"env": {
"PYTHONPATH": "/path/to/mcp/src"
}
}
```
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建一个功能分支（`git checkout -b feature/amazing-feature`）
3. 进行更改并添加测试
4. 运行测试套件（`python tests/test_e2e.py`）
5. 提交更改（`git commit -m '添加惊人功能'`）
6. 推送到分支（`git push origin feature/amazing-feature`）
7. 打开拉取请求
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## 致谢
- 使用 [Model Context Protocol SDK](https://github.com/modelcontextprotocol/python-sdk) 构建
- 使用 [pywemo](https://github.com/pywemo/pywemo) 进行 WeMo 设备通信
- 与 [wemo-ops-center](https://github.com/qrussell/wemo-ops-center) 项目相关（桌面和服务器应用程序）
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器