WeMo MCP Server

WeMo MCP服务器

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

mcp-name: io.github.apiarya/wemo

目录

• 概述
• 先决条件
• 快速开始
• 连接
• 配置
• MCP工具

- 扫描网络 - 列表_设备 - get_device_status - 控制装置 - 重命名_设备 - get_homekit_code - get_ache_info - clear_cache - getconfig配置

• MCP能力

- 资源 - 提示 - 精英

• 运作原理

- 本地控制信号流

• 功能对比
• 发展
• 贡献
• 许可证
• 致谢

概述

通过模型上下文协议将WeMo智能家居设备与AI助手无缝集成。建立在 皮韦莫，该服务器通过智能多阶段发现实现了对WeMo设备的自然语言控制。

示例用法

*通过自然语言的人工智能助手控制WeMo设备——只需用简单的英语提问！*

*“晚安”——一个命令关闭房子里的所有设备*

主要特点

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

______________________________________________________________________

先决条件

所有配置都使用 uvx （从 uv Python包管理器）来运行服务器。安装 紫外线 第一：

# 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

______________________________________________________________________

连接

一键安装

单击您的客户端立即安装：

手动配置

克劳德桌面版

编辑 ~/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代码。

光标

编辑 ~/.cursor/mcp.json:

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

保存后重新启动Cursor。

克莱恩

Cline是一个VS Code扩展。添加到VS代码 settings.json:

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

保存后重新加载VS代码。

帆板运动

编辑 ~/.windsurf/mcp.json:

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

保存后重新启动Windsurf。

泽德

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

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

保存后重新启动Zed。

继续

Continue是一个VS代码扩展名。编辑 ~/.continue/config.json:

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

保存后重新加载VS代码。

______________________________________________________________________

配置

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

快速配置

最重要的设置是你的 网络子网 --服务器默认为 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

使用YAML配置文件:

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

配置选项

示例配置

大型网络 （多个子网）：

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.示例 获取完整的配置模板。

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

______________________________________________________________________

MCP工具

1.扫描网络

使用智能多相位扫描在您的网络上发现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.设备列表

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

示例提示：

• “列出我的所有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.设备状态

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

示例提示：

• “办公室的灯亮着吗？”
• “卧室灯的状况如何？”
• “检查客厅开关”
• “办公室的灯有多亮？”

示例响应：

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

4.控制装置

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

示例提示：

• “打开办公室灯”
• “关掉客厅”
• “打开卧室灯”
• “将办公室照明设置为75%”
• “将卧室灯调暗至50%”

示例响应：

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

5.重命名_设备

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

示例提示：

• “将Office调光器重命名为Office 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.获取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.获取缓存信息

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

示例提示：

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

示例响应：

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.获取配置

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

示例提示：

• “显示服务器配置”
• “当前设置是什么？”
• “显示配置”

示例响应：

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原语。

资源

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

支持MCP资源（VS代码、MCP检查器）的客户端可以直接读取这些资源。

提示

通过以下方式提供四个内置引导提示 / 支持客户端的斜线命令：

*所有四个提示都显示为 /mcp.wemo.* VS代码中的斜线命令*

精英

服务器主动请求缺少的信息，而不是默默地失败：

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

*激发作用——服务器请求子网，而不是默默地扫描错误的网络*

客户支持矩阵

______________________________________________________________________

运作原理

多阶段发现

服务器使用针对可靠性优化的三阶段发现过程：

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

- 多播发现找到所有响应设备（~12秒） - 最可靠的方法，发现对端口探测没有响应的设备 - 使用pywemo的内置发现机制

1. 第2阶段-网络端口扫描（备份）

- 跨子网并行探测WeMo端口（49152-49155） - 60个并发工作者用于快速扫描（254个IP约10秒） - 捕获UPnP错过的设备

1. 第3阶段-设备验证（备份）

- 通过/setup.xml对活动IP进行HTTP验证 - 与60名工人进行平行验证 - 验证并提取设备信息

这种方法实现了 100%设备发现可靠性 同时保持快速扫描时间（完整网络为23-30秒）。

本地控制信号流

所有设备命令仅在您的 本地网络 --在任何阶段都不需要云跳跃。

语音路径（谷歌主页+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!"

两条路径都使用 仅限本地协议 在最初的语音识别之后（谷歌云处理语音转文本；贝尔金的云从未参与其中）。

功能对比

MCP服务器与wemo运营中心

此MCP服务器与主MCP服务器的功能比较 韦莫行动中心 项目：

传说：

• ✅ 实现 -功能可用
• ❌ 未计划的 -功能与MCP架构或用例冲突
• ❌ 计划的 -将来可能会添加功能

为什么MCP没有计划一些功能：

• 调度：需要24/7后台守护进程轮询。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. 分叉存储库
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. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 内置于 模型上下文协议SDK
• 用途 皮韦莫 用于WeMo设备通信
• 与the 韦莫行动中心 项目（桌面和服务器应用程序）