Homey Mcp

HomeyPro MCP サーバー

HomeyPro ホームオートメーションシステムと連携するための Model Context Protocol（MCP）サーバーです。このサーバーでは、デバイス、ゾーン、フローにページネーションでアクセスでき、包括的な管理機能を利用できます。

機能

• デバイス管理：すべての機能をサポートし、デバイスの一覧表示、検索、制御ができます
• ゾーン管理：ゾーンと関連するデバイスを確認できます
• フロー管理：オートメーションフローの一覧表示と実行ができます
• システム管理：システム設定（場所、住所、言語、単位）の取得と更新ができます
• AI を活用したプロンプト：デバイス制御、トラブルシューティング、オートメーションに関する状況に応じたガイダンスを提供します
• リソースのキャッシュ：インテリジェントなキャッシュと古いデータへのフォールバックにより、効率的にデータにアクセスできます
• ページネーションのサポート：カーソルベースのページネーションにより、大規模なデータセットを効率的に処理できます
• リアルタイムデータ：現在のデバイス状態、機能、インサイトを取得できます
• エラー処理：詳細なエラーメッセージを含む、包括的なエラー処理を行います

インストール

ローカル開発

1. リポジトリをクローンし、プロジェクトディレクトリに移動します：

cd python-homey-mcp

2. uv を使用して依存関係をインストールします：

uv sync

Docker

ビルド済みの Docker イメージを取得します（AMD64 と ARM64 の両アーキテクチャに対応しています）：

docker pull ghcr.io/pigmej/python-homey-mcp:latest

Docker イメージは複数のアーキテクチャ向けにビルドされています：

• linux/amd64 - Intel／AMD プロセッサ向け
• linux/arm64 - ARM プロセッサ向け（Apple Silicon、Raspberry Pi など）

Docker はシステムに適したアーキテクチャを自動的に取得します。

マルチアーキテクチャイメージのビルド

独自のマルチアーキテクチャ Docker イメージをビルドするには：

# Setup Docker Buildx (one-time setup)
./setup-buildx.sh

# Build for current platform only
make docker-build

# Build for both AMD64 and ARM64
make docker-build-multi

# Build and push to registry
make docker-push

Docker を使用する場合、追加のインストール手順は不要です。

設定

サーバーを実行する前に、HomeyPro への接続を設定する必要があります：

環境変数

以下の環境変数を設定します：

export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

オプションのツール設定

デフォルトでは、すべての個別ツールが有効です。モデルの混乱を減らすため、特定のツールを個別に無効または有効にできます：

特定のツールを無効にする

特定の個別ツールを無効にするには、環境変数 HOMEY_DISABLED_TOOLS を設定します：

# Disable device control and insights tools (keep device listing and search)
export HOMEY_DISABLED_TOOLS="control_device,get_device_insights"

# Disable all device management tools
export HOMEY_DISABLED_TOOLS="list_devices,get_device,get_devices_classes,get_devices_capabilities,search_devices_by_name,search_devices_by_class,control_device,get_device_insights"

特定のツールのみを有効にする

特定の個別ツールのみを有効にするには、環境変数 HOMEY_ENABLED_TOOLS を設定します：

# Enable only system info and zone listing (minimal configuration)
export HOMEY_ENABLED_TOOLS="get_system_info,list_zones"

# Enable basic device and zone management without control capabilities
export HOMEY_ENABLED_TOOLS="get_system_info,list_devices,get_device,list_zones,get_zone_devices"

利用可能な個別ツール：

デバイスツール：

• list_devices - ページネーションでデバイスをすべて一覧表示
• get_device - デバイスの詳細情報を取得
• get_devices_classes - 利用可能なデバイスクラスを一覧表示
• get_devices_capabilities - 利用可能なデバイス機能を一覧表示
• search_devices_by_name - 名前でデバイスを検索
• search_devices_by_class - クラスでデバイスを検索
• control_device - デバイスの機能を制御
• get_device_insights - デバイスのインサイト／分析情報を取得

フローツール：

• list_flows - 通常のフローと高度なフローをすべて一覧表示
• trigger_flow - 特定のフローを実行
• get_flow_folders - フォルダー構成を取得
• get_flows_by_folder - 特定のフォルダー内のフローを取得
• get_flows_without_folder - どのフォルダーにも属していないフローを取得

ゾーンツール：

• list_zones - すべてのゾーンを一覧表示
• get_zone_devices - 特定のゾーン内のデバイスを取得
• get_zone_temp - ゾーンの温度データを取得

システムツール：

• get_system_info - システム情報と統計情報を取得

注： プロンプトとリソースは、ツールの設定にかかわらず常に利用できます。

利用可能なツールの一覧表示

現在有効になっているツールを確認するには、FastMCP の組み込みメソッド list_tools() を使用できます。無効になっているツールはこの一覧に表示されません。これは意図した動作です。

MCP サーバーの実行中は、有効になっているツールのみがクライアントから利用できます。

実装に関する注意事項

ツールには標準の @mcp.tool() デコレーターを使用し、起動後に設定します。

• すべてのツールを通常どおり @mcp.tool() で登録します。
• 登録後、FastMCP の .disable() メソッドを使ってツールを選択的に無効化します。
• 環境変数を処理し、無効化するツールを決定します。
• 無効化されたツールは list_tools() に表示されず、呼び出すこともできません。

この方法ならコードをシンプルに保ちながら、FastMCP のネイティブなツール管理機能を活用できます。

HomeyPro トークンの取得

1. HomeyPro のウェブインターフェースを開きます。
2. Settings > General > API に移動します。
3. 新しい Personal Access Token を作成します。
4. トークンをコピーし、HOMEY_API_TOKEN 環境変数に設定します。

HomeyPro の IP アドレスを確認する

HomeyPro の IP アドレスは、次の場所で確認できます。

• HomeyPro のウェブインターフェース：Settings > General > Network
• ルーターの管理パネル
• HomeyPro のモバイルアプリ：More > Settings > General > Network

使い方

サーバーの実行

uvx を使用する（推奨）

サーバーを実行する最も簡単な方法は、uvx を使用することです。

# Set your environment variables
export HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS"
export HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

# Run with uvx
uvx --from . homey-mcp

または、FastMCP CLI から直接実行します。

# HTTP transport (recommended for testing)
uvx fastmcp run main.py --transport http --host 0.0.0.0 --port 4445

# STDIO transport (for MCP clients)
uvx fastmcp run main.py --transport stdio

ローカル開発

# Using uv run
uv run fastmcp run main.py --transport http --host 0.0.0.0 --port 4445 --log-level DEBUG

# Or the old way
uv run fastmcp run -t http --host 0.0.0.0 -p 4445 -l DEBUG main.py

# Or using Makefile
make run

開発コマンド

このプロジェクトには、便利な開発コマンドを含む包括的な Makefile が用意されています。

# Setup and installation
make setup              # Initial setup (install + check environment)
make install            # Install dependencies
make check-env          # Verify environment configuration

# Development workflow
make test               # Run test suite
make lint               # Run linting checks
make format             # Format code
make clean              # Clean up generated files

# Docker operations
make docker-build       # Build Docker image for current platform
make docker-build-multi # Build multi-architecture image (AMD64 + ARM64)
make docker-push        # Build and push multi-architecture image
make docker-test        # Test Docker image

# Utilities
make info               # Show project information
make check-connection   # Test HomeyPro connection

MCP クライアントへのインストール

FastMCP を使って、このサーバーを MCP クライアントに直接インストールできます。

# Install in Claude Desktop
uvx fastmcp install claude-desktop main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

# Install in Claude Code
uvx fastmcp install claude-code main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

# Install in Cursor
uvx fastmcp install cursor main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

# Generate MCP JSON config
uvx fastmcp install mcp-json main.py \
  --env-var HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS \
  --env-var HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

Docker コンテナー

MCP サーバーを Docker コンテナー内で実行します。

docker run -p 4445:4445 \
  -e HOMEY_API_URL="http://YOUR_HOMEY_IP_ADDRESS" \
  -e HOMEY_API_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN" \
  ghcr.io/pigmej/python-homey-mcp:latest

または、docker-compose を使用します。

version: '3.8'
services:
  python-homey-mcp:
    image: ghcr.io/pigmej/python-homey-mcp:latest
    ports:
      - "4445:4445"
    environment:
      - HOMEY_API_URL=http://YOUR_HOMEY_IP_ADDRESS
      - HOMEY_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN

サーバーが起動し、HomeyPro インスタンスに接続します。接続確認メッセージが表示されます。ただし、基本的には FastMCP のドキュメントを参照してください。

AI を活用したプロンプト

このサーバーは、HomeyPro システムをより効果的に操作できるよう、状況に応じたプロンプトを提供します。これらのプロンプトは現在のシステム状態を分析し、個々の状況に合わせたガイダンスを提示します。

利用可能なプロンプト

デバイス制御アシスタント

HomeyPro システム内のさまざまな種類のデバイスを制御するための、体系的なガイダンスを提供します。

• コンテキスト：現在のデバイス数、オンライン／オフラインの状態、利用可能なデバイスの種類
• ガイダンス：照明、空調、セキュリティ、エンターテインメント機器の制御パターン
• ベストプラクティス：デバイスの状態確認、機能の活用、トラブルシューティングのヒント

デバイスのトラブルシューティング

HomeyPro デバイスでよくある問題に対する、体系的な診断ガイダンスです。

• システムの健全性：デバイス全体の健全性の割合と状態インジケーター
• 段階的な手順：体系的なトラブルシューティングのワークフロー
• デバイス固有の対応：オフラインまたは応答しないデバイスへの対象を絞った解決策
• 高度な診断：ネットワーク、パフォーマンス、システムレベルのトラブルシューティング

デバイス機能の探索

詳細に圧倒されることなく、デバイスの機能を見つけて理解できるよう支援します。

• 機能のカテゴリ：制御、センサー、状態に関する機能
• 値の型：ブール値、数値、文字列、列挙型の機能形式
• 使用パターン：一般的な機能の組み合わせとベストプラクティス
• デバイスの種類ごとのパターン：さまざまなデバイスカテゴリにおける機能のパターン

フロー作成アシスタント

HomeyPro の自動化フローを作成するための、体系的なガイダンスを提供します。

• フローの枠組み：WHEN（トリガー）、AND（条件）、THEN（アクション）の構造
• 一般的なシナリオ：セキュリティ、快適性、エネルギー、利便性、安全のための自動化
• システムのコンテキスト：利用可能なゾーン、デバイスの種類、既存のフロー
• テンプレート：一般的な用途ですぐに使えるフローテンプレート

フローの最適化

既存のフローのパフォーマンスと信頼性を向上させるためのガイダンスです。

• パフォーマンス分析：フローの実行パターンと最適化の機会
• リソースの使用状況：デバイスとシステムのリソースに関する考慮事項
• ベストプラクティス：フローの整理、命名、保守の方法

フローのデバッグ

フローの問題を診断し、修正するための体系的なアプローチです。

• よくある問題：フローの実行失敗、タイミングの問題、デバイスの競合
• 診断ツール：ログ分析、条件のテスト、アクションの検証
• 解決方法：段階的なデバッグのワークフロー

システムのヘルスチェック

システムの状態を包括的に分析し、推奨事項を提示します。

• ヘルス指標：デバイスの接続状況、フローの状態、システムのパフォーマンス
• ステータスの概要：接続状態、システム構成、リソース使用状況
• 推奨事項：メンテナンスの提案と最適化の機会

ゾーンの整理

ゾーン構成の整理と最適化に関するガイダンスです。

• ゾーンの計画：デバイスやエリアを論理的にグループ化する方法
• 階層の管理：親子関係にあるゾーンの管理
• デバイスの割り当て：デバイスをゾーンに割り当てる際のベストプラクティス

プロンプトの機能

• コンテキストを認識：すべてのプロンプトが現在のシステム状態を分析します
• リアルタイムデータ：現在のデバイスとシステムの状態に基づく情報です
• 段階的な機能低下：HomeyPro が一時的に利用できない場合でもプロンプトが動作します
• エラー処理：推奨される対応策を含む明確なエラーメッセージを表示します
• すぐに実行できるガイダンス：すぐに実行できる実践的な手順を提示します

リソースのキャッシュ

このサーバーは、HomeyPro が一時的に利用できない場合に古いデータへ自動的にフォールバックする、インテリジェントなリソースキャッシュを提供します。

利用可能なリソース

システムの概要（homey://system/overview）

デバイス数、ゾーン数、ヘルス指標を含む、システムの包括的な概要です。

• 内容：デバイスの統計、ゾーンの概要、システムのヘルス割合
• キャッシュ TTL：5 分
• 用途：ダッシュボードの表示、システムの監視、ヘルスチェック

デバイスレジストリ（homey://devices/registry）

現在の状態、機能、オンライン／オフラインの指標を含む、デバイスの完全な一覧です。

• 内容：機能、状態、メタデータを含むすべてのデバイスの一覧
• キャッシュ TTL：30 秒（動的データ）
• 用途：デバイス管理インターフェース、機能の検出、ステータスの監視

ゾーン階層（homey://zones/hierarchy）

デバイスの関連付けと親子関係を含むゾーン構成です。

• 内容：ゾーンツリー、デバイスの割り当て、ゾーンの種類と統計
• キャッシュ TTL：5 分
• 用途：ゾーンの管理、デバイスの整理、空間オートメーション

フローカタログ（homey://flows/catalog）

メタデータ、ステータス、実行統計を含む利用可能なフローです。

• 内容：トリガー、条件、アクション、実行データを含むフローの一覧
• キャッシュ TTL：2 分
• 用途：フローの管理、オートメーションの分析、デバッグ

キャッシュ機能

• インテリジェントな TTL：データの変動性に応じてキャッシュ期間を設定します
• 古いデータへのフォールバック：HomeyPro に接続できない場合、キャッシュされたデータを返します
• エラー処理：詳細なエラー情報を提示し、段階的に機能を低下させます
• 接続の回復力：ネットワークに問題が発生している間も動作を継続します
• パフォーマンスの最適化：API 呼び出しを減らし、応答時間を改善します

キャッシュの動作

1. 最新データ：キャッシュが有効で HomeyPro に接続できる場合、現在のデータを返します
2. 古いデータ：HomeyPro に接続できない場合、古さを示す情報とともにキャッシュされたデータを返します
3. エラーレスポンス：キャッシュされたデータがない場合、構造化されたエラー情報を返します
4. 自動更新：HomeyPro が再び利用可能になると、キャッシュは自動的に更新されます

API ツール

このサーバーは、HomeyPro を直接操作するための包括的な API ツールを提供します。すべてのツールが、詳細なレスポンスを伴うページネーションとエラー処理に対応しています。

デバイスツール

デバイスの検出と情報

• list_devices：ページネーションに対応してすべてのデバイスを一覧表示します

  • データ転送量を抑えるコンパクトモード（任意）
  • 非表示のデバイスを自動的に除外します
  • 各デバイスのオンライン／オフライン状態を含みます

• get_device：特定のデバイスに関する詳細情報を取得します

  • 機能や設定を含むデバイスの完全な詳細情報
  • 機能の値と詳細な設定
  • エネルギー情報とUI設定

• get_devices_classes：利用可能なすべてのデバイスクラスを一覧表示します

  • 検索前にデバイスの種類を把握するのに便利です
  • サポートされているデバイスカテゴリの完全な一覧を返します

• get_devices_capabilities：考えられるすべてのデバイス機能を一覧表示します

  • 包括的な機能リファレンス
  • 制御オプションを理解するために不可欠です

デバイスの検索とフィルタリング

• search_devices_by_name：ページネーションに対応して名前でデバイスを検索します

  • デバイス名とのあいまい一致
  • コンテキスト把握のためのメモ欄の情報を含みます
  • 大規模な結果セットのページネーションに対応します

• search_devices_by_class：クラス／種類でデバイスを検索します

  • 特定のカテゴリ（照明、センサーなど）でデバイスを絞り込みます
  • メタデータ付きのページネーション対応結果

デバイスの制御とモニタリング

• control_device：デバイスの機能を制御します

  • 機能の値を設定します（オン／オフ、調光、温度など）
  • フォールバック処理に対応したJSON値の解析
  • 制御後のデバイスの現在の状態を返します

• get_device_insights：デバイスの履歴データを取得します

  • 複数の時間解像度（時間、日、週、月）
  • カスタムのタイムスタンプ範囲に対応します
  • 機能ごとの分析情報と傾向

ゾーンツール

ゾーン管理

• list_zones：ページネーションに対応してすべてのゾーンを一覧表示します

  • ゾーン階層の完全な情報
  • 親子関係を含みます

• get_zone_devices：特定のゾーン内のすべてのデバイスを取得します

  • ゾーンに基づくデバイスのフィルタリング
  • パフォーマンス向上のためのコンパクトモードオプション
  • デバイスごとのオンライン／オフライン状態

ゾーンのモニタリング

• get_zone_temp：ゾーンの平均温度を取得します
  • ゾーン内の温度センサーの平均を自動的に計算します
  • 温度センサーがないゾーンも適切に処理します

フローツール

統合フロー管理

• list_flows：ページネーションに対応して、通常フローと高度なフローの両方を一覧表示します

  • 通常フローと高度なフローを自動的に統合します
  • 各フローには flow_type フィールド（「normal」または「advanced」）が含まれます
  • フローのメタデータと設定をすべて含みます
  • 統合された結果に対してシームレスにページネーションできます

• trigger_flow：任意のフローを実行します（種類を自動判別）

  • フローが通常か高度かを自動的に判別します
  • 統一インターフェースでフローを手動実行します
  • フローの詳細と種類を含む成功確認

• get_flow_folders：フローを整理するすべてのフォルダーを取得します

  • フローの整理構造
  • 管理しやすくするためのフォルダー階層

• get_flows_by_folder：特定のフォルダー内のフローを取得します

  • フォルダーに基づくフローのフィルタリング
  • フローの整理と管理

• get_flows_without_folder：未整理のフローを取得します

  • 整理が必要なフローを見つけます
  • 整理とメンテナンスを支援します

フローの整理

• get_flow_folders：フローを整理するすべてのフォルダーを取得します

  • フローの整理構造
  • 管理しやすくするためのフォルダー階層

• get_flows_by_folder：特定のフォルダー内のフローを取得します

  • フォルダーに基づくフローのフィルタリング
  • フローの整理と管理
  • 注：フォルダー内の通常フローのみを返します

• get_flows_without_folder：未整理のフローを取得します

  • 整理が必要なフローを見つけます
  • 整理とメンテナンスを支援します
  • 注：フォルダーに属さない通常フローのみを返します

システムツール

システム情報

• get_system_info：システムの概要を包括的に取得します
  • 接続状態とシステムの健全性
  • デバイス、ゾーン、フローの数
  • オンライン／オフラインのデバイス統計
  • フローの状態（有効／無効／破損）
  • システム設定（アドレス、言語、単位）
  • 位置座標と地域設定
  • 他の操作を行う前に最初に呼び出すことを推奨します

ツールの機能

ページネーションのサポート

• カーソルベースのページネーション：大規模なデータセットを効率的に処理します
• 設定可能なページサイズ：用途に合わせて最適化できます
• 合計件数の追跡：データセット全体のサイズを把握できます
• 次ページのインジケーター：結果を簡単に移動できます

データ形式

• コンパクトモード：パフォーマンス向上のためデータ転送量を削減します
• 詳細モード：必要に応じて完全な情報を取得します
• JSON 値の処理：フォールバック付きで自動的に解析します
• エラーレスポンス：詳細を含む構造化されたエラー情報を返します

パフォーマンスの最適化

• 非表示デバイスのフィルタリング：システムデバイスを自動的に除外します
• 効率的なクエリ：HomeyPro への API 呼び出しを最適化します
• 接続の再利用：パフォーマンス向上のため接続を維持します
• 段階的な縮退：一部で障害が発生しても処理を継続します

エラー処理

• 詳細なエラーメッセージ：問題を明確に説明します
• 接続状態：ネットワークと API の健全性を示します
• フォールバックレスポンス：API 障害に対して適切に処理します
• ログ連携：エラーを包括的に追跡します

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。