Content
# WeMo MCP Server
Control WeMo smart home devices through AI assistants using natural language.
**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)
## Table of Contents
- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Connect](#connect)
- [Configuration](#configuration)
- [MCP Tools](#mcp-tools)
- [scan_network](#1-scan_network)
- [list_devices](#2-list_devices)
- [get_device_status](#3-get_device_status)
- [control_device](#4-control_device)
- [rename_device](#5-rename_device)
- [get_homekit_code](#6-get_homekit_code)
- [get_cache_info](#7-get_cache_info)
- [clear_cache](#8-clear_cache)
- [get_configuration](#9-get_configuration)
- [MCP Capabilities](#mcp-capabilities)
- [Resources](#resources)
- [Prompts](#prompts)
- [Elicitations](#elicitations)
- [How It Works](#how-it-works)
- [Local Control Signal Flow](#local-control-signal-flow)
- [Feature Comparison](#feature-comparison)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Overview
Seamlessly integrate WeMo smart home devices with AI assistants through the Model Context Protocol. Built on [pywemo](https://github.com/pywemo/pywemo), this server enables natural language control of your WeMo devices with intelligent multi-phase discovery.
### Example Usage
*Control WeMo devices through AI assistants with natural language - just ask in plain English!*
*"Goodnight" — one command turns off every device in the house*
### Key Features
- **🔍 Smart Discovery** - Multi-phase scanning (UPnP/SSDP + network ports) with 100% reliability
- **⚡ Fast Scanning** - Parallel probes with 60 concurrent workers (~23-30s for full subnet)
- **🎛️ Full Control** - On/off/toggle/brightness control for all device types
- **✏️ Device Management** - Rename devices and extract HomeKit setup codes
- **📊 Real-time Status** - Query device state and brightness
- **💾 Smart Caching** - Persistent device cache with 1-hour TTL survives restarts
- **🔧 Configurable** - YAML config files + environment variables for all settings
- **🔄 Auto-Retry** - Automatic retry with exponential backoff for network errors
- **🛡️ Error Handling** - Detailed error messages with actionable suggestions
- **🔌 Universal** - Works with any MCP client (Claude, VS Code, Cursor, etc.)
- **📡 MCP Resources** - Live device state via `devices://` and `device://{id}` URIs
- **💬 MCP Prompts** - Built-in guided prompts: discover, status report, scene control, troubleshoot
- **🗣️ MCP Elicitations** - Interactive clarification when subnet or device name is ambiguous
---
## Prerequisites
All configurations use `uvx` (from the `uv` Python package manager) to run the server. Install [uv](https://docs.astral.sh/uv/) first:
```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"
```
After installation, restart your terminal and verify:
```bash
uvx --version
```
## Quick Start
Get started in seconds with Claude Code CLI:
```bash
claude mcp add wemo -- uvx wemo-mcp-server
```
---
## Connect
### One-Click Installation
Click your client to install instantly:
| Client | Install |
|--------|---------|
| **Claude Desktop** | [](https://modelcontextprotocol.io/quickstart/user) |
| **Claude Code CLI** | Run: `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** | [Manual config](#cline) (VS Code extension) |
| **Windsurf** | [Manual config](#windsurf) |
| **Zed** | [Manual config](#zed) |
| **Continue** | [Manual config](#continue) (VS Code extension) |
### Manual Configuration
#### Claude Desktop
Edit `~/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"
}
}
}
}
```
Restart Claude Desktop after saving.
#### VS Code
Edit `~/.vscode/mcp.json`:
```json
{
"servers": {
"wemo": {
"type": "stdio",
"command": "uvx",
"args": ["wemo-mcp-server"],
"env": {
"WEMO_MCP_DEFAULT_SUBNET": "192.168.1.0/24"
}
}
}
}
```
Reload VS Code after saving.
#### Cursor
Edit `~/.cursor/mcp.json`:
```json
{
"servers": {
"wemo": {
"type": "stdio",
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
Restart Cursor after saving.
#### Cline
Cline is a VS Code extension. Add to VS Code's `settings.json`:
```json
{
"mcp.servers": {
"wemo": {
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
Reload VS Code after saving.
#### Windsurf
Edit `~/.windsurf/mcp.json`:
```json
{
"mcpServers": {
"wemo": {
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
Restart Windsurf after saving.
#### Zed
Edit `~/.config/zed/settings.json`:
```json
{
"context_servers": {
"wemo": {
"command": "uvx",
"args": ["wemo-mcp-server"]
}
}
}
```
Restart Zed after saving.
#### Continue
Continue is a VS Code extension. Edit `~/.continue/config.json`:
```json
{
"mcpServers": [
{
"name": "wemo",
"command": "uvx",
"args": ["wemo-mcp-server"]
}
]
}
```
Reload VS Code after saving.
---
## Configuration
The WeMo MCP Server supports flexible configuration through YAML files and environment variables.
### Quick Configuration
The most important setting is your **network subnet** — the server defaults to `192.168.1.0/24` but your devices may be on a different subnet (e.g. `192.168.86.0/24`).
Set it directly in your MCP client config using `env`:
```json
"env": {
"WEMO_MCP_DEFAULT_SUBNET": "192.168.86.0/24"
}
```
Or export it before starting the server:
**Using Environment Variables** (simplest):
```bash
export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_CACHE_TTL=7200
export WEMO_MCP_LOG_LEVEL=DEBUG
```
**Using YAML Config File**:
```bash
# Copy example config and customize
cp config.example.yaml config.yaml
# Edit config.yaml with your settings
```
### Configuration Options
| Setting | Environment Variable | Default | Description |
|---------|---------------------|---------|-------------|
| **Network** ||||
| Default subnet | `WEMO_MCP_DEFAULT_SUBNET` | `192.168.1.0/24` | Network to scan for devices |
| Scan timeout | `WEMO_MCP_SCAN_TIMEOUT` | `0.6` | Port probe timeout (seconds) |
| Max workers | `WEMO_MCP_MAX_WORKERS` | `60` | Concurrent scanning threads |
| **Cache** ||||
| Enable cache | `WEMO_MCP_CACHE_ENABLED` | `true` | Persistent device caching |
| Cache file | `WEMO_MCP_CACHE_FILE` | `~/.wemo_mcp_cache.json` | Cache file location |
| Cache TTL | `WEMO_MCP_CACHE_TTL` | `3600` | Cache lifetime (seconds) |
| **Logging** ||||
| Log level | `WEMO_MCP_LOG_LEVEL` | `INFO` | DEBUG, INFO, WARNING, ERROR |
### Example Configurations
**Large Network** (multiple subnets):
```bash
export WEMO_MCP_DEFAULT_SUBNET="10.0.0.0/16"
export WEMO_MCP_SCAN_TIMEOUT=1.0
export WEMO_MCP_MAX_WORKERS=100
```
**Debug Mode**:
```bash
export WEMO_MCP_LOG_LEVEL=DEBUG
export WEMO_MCP_CACHE_TTL=300 # 5 minutes
```
**Disable Caching**:
```bash
export WEMO_MCP_CACHE_ENABLED=false
```
See [config.example.yaml](config.example.yaml) and [.env.example](.env.example) for complete configuration templates.
For detailed configuration guide, see [CONFIGURATION.md](CONFIGURATION.md).
---
## MCP Tools
### 1. scan_network
Discover WeMo devices on your network using intelligent multi-phase scanning.
**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
...
```
### 2. list_devices
List all devices cached from previous scans.
**Example Prompts:**
- "List all my WeMo devices"
- "Show me all devices"
- "What devices do you know about?"
**Example Response:**
```
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
Get current state and information for a specific device.
**Example Prompts:**
- "Is the office light on?"
- "What's the status of the bedroom lamp?"
- "Check the living room switch"
- "What's the brightness of office light?"
**Example Response:**
```
Office Light (Dimmer):
- State: OFF
- Brightness: 75%
- IP: 192.168.1.100
- Model: DimmerLongPress
```
### 4. control_device
Control a WeMo device (on/off/toggle/brightness).
**Example Prompts:**
- "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%"
**Example Response:**
```
✓ Office Light turned ON
Brightness set to 75%
Current state: ON
```
### 5. rename_device
Rename a WeMo device (change its friendly name).
**Example Prompts:**
- "Rename Office Dimmer to Office Light"
- "Change the name of the bedroom device to Bedroom Lamp"
- "Call the living room switch 'Main Light'"
**Example Response:**
```
✓ 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
Get the HomeKit setup code for a WeMo device.
**Example Prompts:**
- "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"
**Example Response:**
```
HomeKit Setup Code for 'Office Light':
123-45-678
Use this code to add the device to Apple Home.
```
**Note:** Not all WeMo devices support HomeKit. If a device doesn't support HomeKit, you'll get an error message.
### 7. get_cache_info
Get information about the persistent device cache.
**Example Prompts:**
- "Show me cache information"
- "Is the device cache expired?"
- "How many devices are cached?"
**Example Response:**
```
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
Clear the persistent device cache to force a fresh scan.
**Example Prompts:**
- "Clear the device cache"
- "Reset the cache and rescan"
- "Delete cached devices"
**Example Response:**
```
✅ Cache cleared successfully
Next scan will discover devices fresh.
Run scan_network to rebuild the cache.
```
**Note:** This clears both the persistent cache file and in-memory cache. After clearing, run `scan_network` to rediscover devices.
### 9. get_configuration
View current server configuration settings.
**Example Prompts:**
- "Show me the server configuration"
- "What are the current settings?"
- "Display configuration"
**Example Response:**
```
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
```
**Note:** Shows all configuration including defaults and environment variable overrides. Use environment variables with `WEMO_MCP_` prefix to customize.
---
## MCP Capabilities
Beyond tools, this server exposes the full suite of MCP primitives.
### Resources
Subscribe to live device data without calling a tool:
| URI | Description |
|-----|-------------|
| `devices://` | JSON index of all cached devices |
| `device://{name-or-ip}` | Live state for a specific device (URL-encoded name supported) |
Clients that support MCP Resources (VS Code, MCP Inspector) can read these directly.
### Prompts
Four built-in guided prompts available via `/` slash commands in supporting clients:
| Prompt | Description |
|--------|-------------|
| `discover-devices` | Guided network scan with subnet selection |
| `device-status-report` | Summary report of all device states |
| `activate-scene` | Control multiple devices as a scene |
| `troubleshoot-device` | Step-by-step device troubleshooting |
*All four prompts surfaced as `/mcp.wemo.*` slash commands in VS Code*
### Elicitations
The server proactively asks for missing information rather than failing silently:
- **`scan_network`** — if no custom subnet is configured (default `192.168.1.0/24`), asks which subnet to scan before proceeding
- **`control_device`** — if a device name isn't found in cache, presents closest matches and asks which device was intended
*Elicitation in action — server asks for the subnet rather than scanning the wrong network silently*
### Client Support Matrix
| Feature | Claude Desktop | VS Code | Cursor | MCP Inspector |
|---------|:--------------:|:-------:|:------:|:-------------:|
| Tools | ✅ | ✅ | ✅ | ✅ |
| Resources | ⚠️ protocol only | ✅ | ✅ | ✅ |
| Prompts | ⚠️ no slash UI | ✅ `/` commands | ✅ | ✅ |
| Elicitations | ✅ v1.1+ | ❌ | ❌ | ✅ v0.20+ |
---
## How It Works
### Multi-Phase Discovery
The server uses a three-phase discovery process optimized for reliability:
1. **Phase 1 - UPnP/SSDP Discovery (Primary)**
- Multicast discovery finds all responsive devices (~12s)
- Most reliable method, finds devices that don't respond to port probes
- Uses pywemo's built-in discovery mechanism
2. **Phase 2 - Network Port Scanning (Backup)**
- Parallel probing of WeMo ports (49152-49155) across subnet
- 60 concurrent workers for fast scanning (~10s for 254 IPs)
- Catches devices missed by UPnP
3. **Phase 3 - Device Verification (Backup)**
- HTTP verification of active IPs via /setup.xml
- Parallel verification with 60 workers
- Validates and extracts device information
This approach achieves **100% device discovery reliability** while maintaining fast scan times (23-30 seconds for complete networks).
### Local Control Signal Flow
All device commands travel exclusively over your **local network** — no cloud hop required at any stage.
**Voice path (Google Home + WeMo):**
```mermaid
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 path (AI assistant + this server):**
```mermaid
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!"
```
Both paths use **local protocols only** after the initial voice recognition (Google Cloud handles speech-to-text; Belkin's cloud is never involved).
## Feature Comparison
### MCP Server vs wemo-ops-center
Comparison of features between this MCP server and the main [wemo-ops-center](https://github.com/qrussell/wemo-ops-center) project:
| Feature | wemo-ops-center | MCP Server | Notes |
|---------|-----------------|------------|-------|
| **Device Discovery** | ✅ UPnP + Port Scan | ✅ Implemented | Multi-phase discovery with 100% reliability |
| **Device Control** | ✅ On/Off/Toggle | ✅ Implemented | Includes brightness control for dimmers |
| **Device Status** | ✅ Real-time | ✅ Implemented | Query by name or IP address |
| **Device Rename** | ✅ Friendly names | ✅ Implemented | Updates device cache automatically |
| **HomeKit Codes** | ✅ Extract codes | ✅ Implemented | For HomeKit-compatible devices |
| **Multi-subnet** | ✅ VLAN support | ❌ Planned | Currently single subnet per scan |
| **WiFi Provisioning** | ✅ Smart setup | ❌ Not planned | Requires PC WiFi connection changes |
| **Scheduling** | ✅ Time + Solar | ❌ Not planned | Requires persistent daemon (incompatible with MCP model) |
| **Maintenance Tools** | ✅ Resets | ❌ Not planned | Factory reset, clear WiFi, clear data |
| **Profile Management** | ✅ Save/Load | ❌ Not planned | WiFi credential profiles for bulk setup |
| **User Interface** | ✅ GUI + Web | ❌ N/A | MCP uses AI assistant interface |
**Legend:**
- ✅ **Implemented** - Feature is available
- ❌ **Not planned** - Feature conflicts with MCP architecture or use case
- ❌ **Planned** - Feature could be added in future
**Why some features aren't planned for MCP:**
- **Scheduling**: Requires 24/7 background daemon polling. MCP servers are typically invoked on-demand by AI assistants, not run as persistent services.
- **WiFi Provisioning**: Requires changing the host PC's WiFi connection to device setup networks, which is disruptive and platform-specific.
- **Maintenance Tools**: Destructive operations (factory reset, etc.) better suited for dedicated GUI with confirmation dialogs.
**Current MCP Coverage:** 5 of 11 core features (45%) - focused on device discovery, monitoring, and control use cases that fit the MCP model.
## Development
### Setup
```bash
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
```
### Running Tests
```bash
# 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
```
### Using Development Version
In your MCP client config, use:
```json
{
"command": "python",
"args": ["-m", "wemo_mcp_server"],
"env": {
"PYTHONPATH": "/path/to/mcp/src"
}
}
```
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. Run the test suite (`python tests/test_e2e.py`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/python-sdk)
- Uses [pywemo](https://github.com/pywemo/pywemo) for WeMo device communication
- Related to the [wemo-ops-center](https://github.com/qrussell/wemo-ops-center) project (desktop and server applications)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available