ccu-mcp

ccu-mcpは、AIアシスタント（Claude、Cursor、その他MCPクライアント）をHomeMaticスマートホームシステムに橋渡しするModel Context Protocol（MCP）サーバーです。CCUの組み込みJSON-RPC API（`/api/homematic.cgi`経由）に直接接続するため、アドオン、XML-API、クラウドサービスは不要です。debmatic、CCU3、OpenCCU（旧RaspberryMatic）を含むあらゆるHomeMatic CCUで動作します。 このサーバーは、デバイス検出、タイプ解決、セッション管理、値変換を処理し、「浴室の温度は？」「開いている窓はありますか？」「リビングの暖房を21度に設定して」「バッテリー残量が少ないデバイスをすべて表示して」といった自然言語の質問を可能にするツールを公開します。また、命名規則に従ったデバイス名の変更、チャンネル名の不一致の検出、デバイスの健全性チェックなどの高度な操作もサポートします。 **主な機能：** - **CCUへの直接接続**：アドオンやクラウドは不要。標準のJSON-RPCエンドポイントを使用。 - **複数のトランスポート**：サブプロセス（stdio）またはスタンドアロンHTTPサーバー（Docker）として実行可能。 - **Dockerサポート**：linux/amd64およびlinux/arm64用のイメージを公開。サプライチェーンセキュリティのための証明書も付属。 - **複数CCUプロファイル**：1つのサーバーから複数のCCU（例：本番と開発）を設定・切り替え可能。 - **セキュリティ**：ベアラートークン認証（自動生成または明示指定）、DNSリバインディング保護、CORS許可リスト、TLSサポート（自己署名証明書のピン留めを含む）、オプションのfail2ban統合。 - **セットアップウィザード**：対話型の`init`コマンドがCCUをプローブし、TLS証明書をピン留めし、ログインをテストし、すぐ使える`.env`ファイルを書き出します。会話型セットアップモードでは、LLMがチャットでプロセスをガイドできます。 - **診断**：`doctor`コマンドが設定をエンドツーエンドで検証します。 - **レート制限**：CCUを保護するためのバーストおよび持続レート制限を内蔵。 - **リソースポーリング**：MCPリソース変更通知のためのオプションのポーリング。 **インストールと使用方法：** - **クイックスタート（stdio）**：`CCU_HOST`と`CCU_PASSWORD`環境変数を設定し、`npx ccu-mcp --stdio`を実行します。`.mcp.json`ファイルでMCPクライアント（例：Claude Code）を設定します。 - **Docker（HTTP）**：イメージをプルし、環境変数で実行し、コンテナのデータボリュームから認証トークンを取得します。サーバーURLとベアラートークンでクライアントを設定します。 - **設定**：すべての設定は環境変数で行います（READMEの表を参照）。インラインenv、`.env`ファイル、シェルエクスポートをサポート。 - **CLIフラグ**：`init`、`doctor`、`secret`、`--stdio`、`--http`、`--env`、`--version`、`--help`。 **セキュリティに関する考慮事項：** - サーバーはデフォルトで平文HTTPを使用しますが、ループバック以外のインターフェースでトークンを提供する場合は警告します。認識するには`MCP_ALLOW_PLAINTEXT=true`を設定します。 - リモートアクセスには、TLS（リバースプロキシまたはネイティブHTTPS）を使用し、403エラーを避けるために`MCP_ALLOWED_HOSTS`を設定します。 - トークンローテーションは、クライアントの中断を避けるための猶予期間付きでサポートされています。 - CORSはデフォルトで拒否です。ブラウザベースのクライアント用にオリジンを許可リストに登録します。 **要件：** Node.js 24以上（ソース/stdio用）またはDocker。実行中のHomeMatic CCUと管理者資格情報。 **クライアント設定例（stdio）：** ```json { "mcpServers": { "ccu-mcp": { "command": "npx", "args": ["ccu-mcp", "--stdio"], "env": { "CCU_HOST": "your-ccu-hostname-or-ip", "CCU_PASSWORD": "your-ccu-admin-password" } } } } ``` **クライアント設定例（HTTP）：** ```json { "mcpServers": { "ccu-mcp": { "url": "http://your-server-ip:3000", "headers": { "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE" } } } } ``` このプロジェクトはオープンソースであり、貢献を歓迎します。OpenSSFベストプラクティスとScorecardのバッジが含まれており、セキュリティと品質に重点を置いていることを示しています。