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 の機能
  • リソース
  • プロンプト
  • Elicitations
• 仕組み
  • ローカル制御のシグナルフロー
• 機能比較
• 開発
• 貢献
• ライセンス
• 謝辞

概要

Model Context Protocol を通じて、WeMo スマートホームデバイスを AI アシスタントにシームレスに統合できます。pywemo をベースに構築されたこのサーバーは、複数フェーズにわたるインテリジェントな検出機能により、自然言語で WeMo デバイスを操作できます。

使用例

自然言語を使って、AI アシスタントから WeMo デバイスを操作できます。英語でそのまま頼むだけです！

「おやすみ」のひと言で、家中のデバイスをすべてオフにできます

主な機能

• 🔍 スマート検出 - 複数段階のスキャン（UPnP/SSDP ＋ ネットワークポート）により、100％の信頼性を実現します
• ⚡ 高速スキャン - 60 個のワーカーによる並列プローブで、サブネット全体を約 23～30 秒でスキャンします
• 🎛️ 完全な制御 - すべてのデバイスタイプでオン／オフ／切り替え／明るさを制御できます
• ✏️ デバイス管理 - デバイス名を変更し、HomeKit のセットアップコードを取得できます
• 📊 リアルタイムステータス - デバイスの状態と明るさを照会できます
• 💾 スマートキャッシュ - 1 時間の TTL を持つ永続的なデバイスキャッシュにより、再起動後も情報が保持されます
• 🔧 設定可能 - すべての設定に YAML 設定ファイルと環境変数を使用できます
• 🔄 自動再試行 - ネットワークエラー発生時に、指数バックオフで自動的に再試行します
• 🛡️ エラー処理 - 実行可能な対処方法を含む詳細なエラーメッセージを表示します
• 🔌 汎用対応 - あらゆる MCP クライアント（Claude、VS Code、Cursor など）で動作します
• 📡 MCP リソース - devices:// と device://{id} URI を介して、デバイスの状態をリアルタイムで確認できます
• 💬 MCP プロンプト - 検出、ステータスレポート、シーン制御、トラブルシューティング用のガイド付きプロンプトを内蔵しています
• 🗣️ MCP エリシテーション - サブネットまたはデバイス名が曖昧な場合に、対話形式で確認します

---

前提条件

すべての設定では、uv Python パッケージマネージャーに含まれる uvx を使用してサーバーを実行します。まず 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 Server は、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）は、これらを直接読み取れます。

プロンプト

対応クライアントで / スラッシュコマンドから利用できる、組み込みのガイド付きプロンプトが 4 つあります。

プロンプト	説明
discover-devices	サブネットを選択して実行する、ガイド付きネットワークスキャン
device-status-report	すべてのデバイス状態の概要レポート
activate-scene	シーンとして複数のデバイスを制御
troubleshoot-device	デバイスのトラブルシューティングをステップごとに実行

4 つのプロンプトはすべて、VS Code で /mcp.wemo.* スラッシュコマンドとして表示されます

エリシテーション

このサーバーは、何もせずに失敗するのではなく、不足している情報を積極的に尋ねます。

• scan_network — カスタムサブネットが設定されていない場合（デフォルトは 192.168.1.0/24）、処理を続行する前にスキャンするサブネットを尋ねます
• control_device — デバイス名がキャッシュ内に見つからない場合、最も近い候補を表示し、対象のデバイスを尋ねます

エリシテーションの動作例 — 誤ったネットワークを黙ってスキャンするのではなく、サーバーがサブネットを尋ねます

クライアント対応マトリックス

機能	Claude Desktop	VS Code	Cursor	MCP Inspector
ツール	✅	✅	✅	✅
リソース	⚠️ プロトコルのみ	✅	✅	✅
プロンプト	⚠️ スラッシュ UI なし	✅ / コマンド	✅	✅
エリシテーション	✅ v1.1+	❌	❌	✅ v0.20+

---

仕組み

複数フェーズの検出

このサーバーでは、信頼性を高めるために最適化された 3 フェーズの検出プロセスを使用します。

1. フェーズ 1 - UPnP/SSDP 検出（プライマリ）

   • マルチキャスト検出によって応答するすべてのデバイスを検出します（約 12 秒）
   • 最も信頼性の高い方法で、ポートプローブに応答しないデバイスも検出します
   • pywemo に組み込まれた検出メカニズムを使用します

2. フェーズ 2 - ネットワークポートスキャン（バックアップ）

   • サブネット全体で WeMo ポート（49152-49155）を並行してプローブします
   • 高速スキャンのため、60 個のワーカーを同時に実行します（254 個の IP で約 10 秒）
   • UPnP で検出できなかったデバイスを捕捉します

3. フェーズ 3 - デバイス検証（バックアップ）

   • /setup.xml を介して、稼働中の IP を HTTP で検証します
   • 60 個のワーカーで並行して検証します
   • デバイス情報を検証し、抽出します

この方法により、ネットワーク全体のスキャンが 23～30 秒で完了する高速性を維持しながら、100% のデバイス検出信頼性を実現します。

ローカル制御のシグナルフロー

すべてのデバイスコマンドはローカルネットワーク内のみを通過します。どの段階でもクラウドを経由する必要はありません。

音声経路（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 で一部の機能を予定していない理由：

• スケジュール設定：24 時間 365 日稼働するバックグラウンドデーモンによるポーリングが必要です。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 ライセンスです。詳細は LICENSE ファイルをご覧ください。

謝辞

• Model Context Protocol SDK を使用して構築
• WeMo デバイスとの通信に pywemo を使用
• wemo-ops-center プロジェクト（デスクトップアプリケーションおよびサーバーアプリケーション）に関連