WeMo MCP Server Configuration Guide

February 22, 2026 · View on GitHub

Complete guide to configuring the WeMo MCP Server for your environment.

Table of Contents

Quick Start

Quickest way to customize settings:

# Set your network subnet
export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"

# Extend cache lifetime to 2 hours
export WEMO_MCP_CACHE_TTL=7200

# Enable debug logging
export WEMO_MCP_LOG_LEVEL=DEBUG

# Start the server
uvx wemo-mcp-server

Method 2: YAML Configuration File

For persistent configuration:

# Copy example config
cp config.example.yaml config.yaml

# Edit with your preferred editor
nano config.yaml

# Server will automatically load config.yaml if present

Configuration Methods

The server loads configuration in this priority order (highest to lowest):

  1. Environment Variables - Override everything
  2. YAML Config File - Persistent settings
  3. Default Values - Built-in defaults

Environment Variables

All settings can be configured with the WEMO_MCP_ prefix:

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
WEMO_MCP_CACHE_TTL=3600
WEMO_MCP_LOG_LEVEL=INFO

Load from .env file:

cp .env.example .env
# Edit .env with your settings
source .env  # or use dotenv loader

YAML Configuration File

The server looks for config.yaml in these locations (in order):

  1. Current working directory: ./config.yaml
  2. User config directory: ~/.config/wemo-mcp/config.yaml
  3. System config directory: /etc/wemo-mcp/config.yaml

Example config.yaml:

network:
  default_subnet: "192.168.1.0/24"
  scan_timeout: 0.6
  max_workers: 60
  retry_attempts: 3
  retry_delay: 0.5

cache:
  enabled: true
  file_path: "~/.wemo_mcp_cache.json"
  ttl_seconds: 3600

logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Configuration Reference

Network Settings

default_subnet

  • Environment: WEMO_MCP_DEFAULT_SUBNET
  • Default: 192.168.1.0/24
  • Format: CIDR notation (e.g., 192.168.1.0/24, 10.0.0.0/16)
  • Description: Network subnet to scan when not specified in scan_network call
  • Examples:
    • 192.168.1.0/24 - Single /24 network (254 hosts)
    • 10.0.0.0/16 - Large /16 network (65,534 hosts)
    • 192.168.0.0/16 - Two /16 networks

scan_timeout

  • Environment: WEMO_MCP_SCAN_TIMEOUT
  • Default: 0.6
  • Range: 0.1 - 5.0 seconds
  • Description: Connection timeout for port probing during network scan
  • Tips:
    • Lower values = faster scan, may miss slow devices
    • Higher values = slower scan, catches all devices
    • Use 1.0 for large networks or WiFi devices
    • Use 0.4 for wired networks with fast devices

max_workers

  • Environment: WEMO_MCP_MAX_WORKERS
  • Default: 60
  • Range: 1 - 200
  • Description: Maximum concurrent threads for parallel scanning
  • Tips:
    • Higher values = faster scan, may overwhelm network/router
    • Lower values = slower scan, gentler on network
    • Use 30-60 for home networks
    • Use 100-150 for enterprise networks
    • Reduce if experiencing network issues

retry_attempts

  • Environment: WEMO_MCP_RETRY_ATTEMPTS
  • Default: 3
  • Range: 1 - 10
  • Description: Number of retry attempts for device operations
  • Note: Applied to control/status operations with exponential backoff

retry_delay

  • Environment: WEMO_MCP_RETRY_DELAY
  • Default: 0.5
  • Range: 0.1 - 5.0 seconds
  • Description: Initial delay between retries (doubles each retry)

Cache Settings

enabled

  • Environment: WEMO_MCP_CACHE_ENABLED
  • Default: true
  • Values: true, false, 1, 0, yes, no
  • Description: Enable/disable persistent device caching
  • Benefits:
    • Faster startup (no scan needed)
    • Survives server restarts
    • Reduces network traffic

file_path

  • Environment: WEMO_MCP_CACHE_FILE
  • Default: ~/.wemo_mcp_cache.json
  • Format: Absolute or relative path
  • Description: Location of cache file
  • Examples:
    • ~/.wemo_mcp_cache.json - User home directory
    • /var/cache/wemo-mcp/devices.json - System cache
    • ./cache.json - Current directory

ttl_seconds

  • Environment: WEMO_MCP_CACHE_TTL
  • Default: 3600 (1 hour)
  • Range: 0 - unlimited
  • Description: Cache time-to-live in seconds
  • Special: 0 = never expire
  • Examples:
    • 300 - 5 minutes (frequent changes)
    • 3600 - 1 hour (balanced)
    • 7200 - 2 hours (stable network)
    • 86400 - 24 hours (rare changes)

Logging Settings

level

  • Environment: WEMO_MCP_LOG_LEVEL
  • Default: INFO
  • Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • Description: Logging verbosity level
  • Recommendations:
    • DEBUG - Development, troubleshooting
    • INFO - Production, normal operation
    • WARNING - Production, only warnings/errors
    • ERROR - Production, only errors

format

  • Environment: WEMO_MCP_LOG_FORMAT
  • Default: %(asctime)s - %(name)s - %(levelname)s - %(message)s
  • Description: Python logging format string
  • Examples:
    • %(levelname)s: %(message)s - Simple format
    • %(asctime)s [%(levelname)s] %(message)s - Compact format
    • %(asctime)s - %(name)s - %(levelname)s - %(message)s - Full format

Example Configurations

Home Network (Default)

Simple home network with standard settings:

export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_SCAN_TIMEOUT=0.6
export WEMO_MCP_MAX_WORKERS=60

Large Network

Enterprise or multi-subnet setup:

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_CACHE_TTL=7200  # 2 hours

IoT/Guest Network

Isolated network with limited devices:

export WEMO_MCP_DEFAULT_SUBNET="192.168.99.0/24"
export WEMO_MCP_SCAN_TIMEOUT=0.8
export WEMO_MCP_MAX_WORKERS=30
export WEMO_MCP_CACHE_TTL=3600

Development/Debug

Maximum verbosity for troubleshooting:

export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/24"
export WEMO_MCP_LOG_LEVEL=DEBUG
export WEMO_MCP_CACHE_TTL=300  # 5 minutes
export WEMO_MCP_CACHE_ENABLED=false  # Disable for testing

Docker/Container

Environment-based configuration for containers:

# Dockerfile or docker-compose.yml
ENV WEMO_MCP_DEFAULT_SUBNET=192.168.1.0/24
ENV WEMO_MCP_CACHE_FILE=/var/cache/wemo/devices.json
ENV WEMO_MCP_CACHE_TTL=7200
ENV WEMO_MCP_LOG_LEVEL=INFO

Multiple Subnets

Scan multiple networks (requires multiple scans):

# First subnet
claude chat "Scan 192.168.1.0/24 for devices"

# Second subnet
claude chat "Scan 10.0.0.0/16 for devices"

# Results are merged in cache

Troubleshooting

No Devices Found

Problem: scan_network finds 0 devices

Solutions:

  1. Check subnet:

    # Find your subnet (macOS/Linux)
ifconfig | grep "inet "
# or
ip addr show

# Use correct subnet
export WEMO_MCP_DEFAULT_SUBNET="your.subnet.0/24"

  2. Increase timeout:

    export WEMO_MCP_SCAN_TIMEOUT=1.5

  3. Check network connectivity:

    # Ping a known WeMo device
ping 192.168.1.100

Slow Scanning

Problem: Network scan takes too long

Solutions:

  1. Reduce workers (if overwhelming network):

    export WEMO_MCP_MAX_WORKERS=30

  2. Reduce timeout (if devices respond quickly):

    export WEMO_MCP_SCAN_TIMEOUT=0.4

  3. Use smaller subnet:

    export WEMO_MCP_DEFAULT_SUBNET="192.168.1.0/28"  # Only 14 hosts

Cache Issues

Problem: Devices not updating or cache corruption

Solutions:

  1. Clear cache manually:

    claude chat "Clear the device cache"

  2. Delete cache file:

    rm ~/.wemo_mcp_cache.json

  3. Disable caching:

    export WEMO_MCP_CACHE_ENABLED=false

  4. Reduce TTL:

    export WEMO_MCP_CACHE_TTL=300  # 5 minutes

Device Control Failures

Problem: Devices found but control commands fail

Solutions:

  1. Enable debug logging:

    export WEMO_MCP_LOG_LEVEL=DEBUG

  2. Check device responsiveness:

    # Use WeMo app to control device
# If WeMo app works, MCP should work

  3. Rescan network:

    claude chat "Clear cache and scan for devices"

Configuration Not Loading

Problem: Environment variables or config file ignored

Solutions:

  1. Verify environment variables:

    env | grep WEMO_MCP

  2. Check config file location:

    ls -la ~/.config/wemo-mcp/config.yaml
ls -la ./config.yaml

  3. Use get_configuration tool:

    claude chat "Show me the current configuration"

  4. Restart server/client after configuration changes

Advanced Topics

Dynamic Configuration

Change settings without restarting:

# Use get_configuration to verify current settings
claude chat "Show current configuration"

# MCP tools respect current environment
# Export new values before next operation
export WEMO_MCP_SCAN_TIMEOUT=1.0
claude chat "Scan for devices"  # Uses new timeout

Configuration Precedence

When multiple configuration sources exist:

Environment Variables  (highest priority)
    ↓
YAML Config File
    ↓
Default Values       (lowest priority)

Example:

  • config.yaml sets scan_timeout: 0.8
  • Environment has WEMO_MCP_SCAN_TIMEOUT=1.0
  • Result: Uses 1.0 (environment wins)

Sharing Configuration

For teams:

  1. Commit config.example.yaml to git
  2. Team members copy and customize locally
  3. Add config.yaml to .gitignore (already done)

For deployment:

  1. Use environment variables in production
  2. Use config files for local development
  3. Document settings in README or wiki

Getting Help

If you're still having issues:

  1. Enable debug logging:

    export WEMO_MCP_LOG_LEVEL=DEBUG

  2. Check logs for error messages

  3. Verify settings:

    claude chat "Show configuration"

  4. Test basic connectivity:

    claude chat "Scan for devices"

  5. Open an issue on GitHub with:

    • Configuration (sanitize IP addresses)
    • Debug logs
    • Network setup description
    • Expected vs actual behavior

See Also