ccu-mcp

ccu-mcp

Claude、Cursor、または任意の MCP クライアントから HomeMatic スマートホームを操作できます。

ccu-mcp は CCU の組み込み JSON-RPC API に接続し、デバイス、部屋、プログラム、システム変数を MCP ツールとして公開します。アドオンも XML-API もクラウドも不要です。ローカルネットワーク上の CCU に直接接続するだけです。

任意の HomeMatic CCU で動作します。debmatic（Debian 上の HomeMatic）、CCU3、OpenCCU（旧 RaspberryMatic）など、標準の /api/homematic.cgi エンドポイントを公開しているものなら使用できます。

どんなことができますか？

AI アシスタントに次のような質問や指示ができます。

• 「浴室の温度は何度ですか？」
• 「開いている窓はありますか？」
• 「リビングの暖房を21度に設定して」
• 「バッテリー残量が少ないデバイスをすべて表示して」
• 「ガスメーターの数値は？」
• 「バッテリー残量が少ない、または長い間応答がないデバイスはどれですか？」
• 「デバイス名と一致しない名前のチャンネルをすべて探して」
• 「階数ラベル（UG/OG/EG）を付けた、一貫性のある命名規則に沿ってすべてのデバイス名を変更して」
• 「窓センサーはどの部屋にありますか？」

MCP サーバーがデバイスの検出、種類の解決、セッション管理、値の変換を処理し、AI はツールを呼び出すだけです。

前提条件

• ネットワーク上からアクセスできる稼働中の HomeMatic CCU（debmatic、CCU3、または OpenCCU — 旧 RaspberryMatic）
• CCU の管理者ユーザー名とパスワード（WebUI へのログインに使うものと同じ認証情報）
• Node.js 24 以降（ソースから実行する場合、または stdio モードの場合）または Docker

クイックスタート

export CCU_HOST=your-ccu-hostname-or-ip
export CCU_PASSWORD=your-ccu-admin-password
npx ccu-mcp --stdio

stderr に server_ready と表示されれば、正常に動作しています。Ctrl+C を押して停止します。次に、MCP クライアントで設定してください。以下を参照してください。

その際に表示される cache_save_failed … mkdir '/data' の行は、この場合は無害ですが、実際に使う際には修正することをおすすめします。CACHE_DIR の既定値は /data（Docker のディレクトリ構成）なので、コンテナ外ではデバイス種類のキャッシュと CCU セッションが実行間で保存されません。書き込み可能な場所を指定してください。 export CACHE_DIR="$HOME/.cache/ccu-mcp"（または .env の同じキー、あるいは env ブロックに指定します）。

ガイド付きセットアップを希望しますか？ npx ccu-mcp init は CCU を検出し、TLS 証明書を固定し、ログインをテストして、すぐに使える .env ファイルを書き込み、対応する MCP クライアント設定を表示します。コマンドラインフラグを参照してください。

インストール

実行方法は2通りあります。stdio（サーバーが MCP クライアントのサブプロセスとして動作）と HTTP（サーバーが Docker で単独動作し、クライアントがネットワーク経由で接続）です。どちらかを選んでください。

オプション A：stdio（直接実行、最も簡単）

最も簡単なセットアップです。MCP クライアント（Claude Code、Cursor など）がサーバーを子プロセスとして起動します。Docker もネットワーク設定も認証トークンも不要です。

Claude Code の場合は、プロジェクトディレクトリ（または Claude Code を使用する任意のディレクトリ）に .mcp.json ファイルを作成してください。

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": ["ccu-mcp", "--stdio"],
      "env": {
        "CCU_HOST": "your-ccu-hostname-or-ip",
        "CCU_PASSWORD": "your-ccu-admin-password"
      }
    }
  }
}

your-ccu-hostname-or-ip を CCU のホスト名（homematic-ccu3 など）または IP アドレス（192.168.1.50 など）に置き換え、your-ccu-admin-password を CCU WebUI へのログインに使うパスワードに置き換えてください。

Claude Code を再起動します。/mcp を実行して接続を確認してください。一覧に ccu-mcp が表示されるはずです。

または、Claude Code CLI を使用します。

claude mcp add ccu-mcp -- npx ccu-mcp --stdio

オプション B：Docker（スタンドアロン HTTP サーバー）

サーバーを独立して実行したい場合に使用します。たとえば、ホームサーバーで実行して複数のクライアントからアクセスできるようにする場合や、MCP クライアントが HTTP リモートに対応している場合です。

1. コンテナーを起動します。 イメージは linux/amd64 および linux/arm64 向けに GHCR で公開されています（CCU の隣にある Raspberry Pi でも動作します）。各アーキテクチャ上でネイティブにビルドされ、アテステーションが付与されています。gh attestation verify oci://ghcr.io/claymore666/ccu-mcp:latest --repo claymore666/ccu-mcp を実行すると、このイメージがこのリポジトリのリリースワークフローから生成されたことを確認できます。

docker pull ghcr.io/claymore666/ccu-mcp:latest

各リリースでは、固有の X.Y.Z タグも公開されます。計画的にアップグレードしたい場合は、latest の代わりにそのタグを固定してください。ソースからビルドする場合は、次のとおりです。

git clone https://github.com/claymore666/ccu-mcp.git && cd ccu-mcp
docker build -t ghcr.io/claymore666/ccu-mcp .

続いて、次のコマンドで実行します。

docker run -d \
  --name ccu-mcp \
  -e CCU_HOST=your-ccu-hostname-or-ip \
  -e CCU_PASSWORD=your-ccu-admin-password \
  -e MCP_ALLOWED_HOSTS=your-server-ip:3000 \
  -v ccu-data:/data \
  -p 3000:3000 \
  ghcr.io/claymore666/ccu-mcp:latest

リモートクライアントには MCP_ALLOWED_HOSTS の設定が必要です。 サーバーの DNS リバインディング保護により、Host ヘッダーが許可リストにないリクエストは拒否されます。デフォルトでは、MCP ポートでの localhost／127.0.0.1／[::1] のみが許可されます。クライアントがサーバーへの接続に使用するすべてのホスト名／IP アドレスを （カンマ区切りで、host:port 形式で）設定してください。設定しなくてもローカルのヘルスチェックは機能しますが、 リモートからの MCP リクエストはすべて 403 Invalid Host header になります。

2. 認証トークンを取得します。 サーバーは初回起動時にランダムなベアラートークンを生成し、コンテナーのデータボリューム内に保存します。MCP クライアントの認証にこのトークンが必要です。次のコマンドで取得します。

docker exec ccu-mcp grep MCP_AUTH_TOKEN /data/.env

MCP_AUTH_TOKEN=e96suzi1iG0H-GPif6K2... のように表示されます。= の後の部分がトークンです。

3. MCP クライアントを設定します。 クライアントで .mcp.json を使用している場合は、HTTP サーバーを追加します。

{
  "mcpServers": {
    "ccu-mcp": {
      "url": "http://your-server-ip:3000",
      "headers": {
        "Authorization": "Bearer PASTE-YOUR-TOKEN-HERE"
      }
    }
  }
}

トークンを自動的に挿入するには、次のコマンドを実行します（jq が必要です）。

TOKEN=$(docker exec ccu-mcp grep MCP_AUTH_TOKEN /data/.env | cut -d= -f2)
jq --arg t "$TOKEN" '.mcpServers["ccu-mcp"].headers.Authorization = "Bearer " + $t' .mcp.json > .mcp.json.tmp && mv .mcp.json.tmp .mcp.json

このコマンドで更新されるのは ccu-mcp エントリーのみです。.mcp.json 内の他のサーバーには影響しません。

4. 正常に動作していることを確認します。

curl http://localhost:3000/health

ブラウザーベースのクライアント（CORS）

デフォルトでは、HTTP サーバーは CORS ヘッダーを一切送信しないため、任意の Web ページからローカルインスタンスを操作することはできません。MCP Inspector などのブラウザーベースの MCP クライアントから直接接続できるようにするには、信頼できるオリジンをカンマ区切りで MCP_ALLOWED_ORIGINS に設定します（例：https://app.example,http://localhost:6274）。Origin が許可リストにあるリクエストには、その正確なオリジンを Access-Control-Allow-Origin に反映します。ローカルインスタンスから実際の CCU ハードウェアを操作できるような、あらゆるサイトへの許可につながるワイルドカード * は使用しません。それ以外のオリジンからのリクエストには CORS ヘッダーを付与せず（ブラウザーがブロックします）、サーバー側でも DNS リバインディング保護によって拒否されます。認証は常に適用され、すべての MCP リクエストでベアラートークンが必要です。

HTTP トランスポートでは、デフォルトでDNS リバインディング保護も有効になっています。設定されたポートで Host ヘッダーが localhost／127.0.0.1／[::1] 以外のリクエストは拒否されます。別のホスト名や IP アドレス（リバースプロキシ、コンテナーの DNS 名、サーバーの LAN アドレスなど）でサーバーにアクセスする場合は、それらのホストを MCP_ALLOWED_HOSTS に追加してください。追加しないと、正当なリクエストも 403 になります。

TLS。 ベアラートークンはリクエスト内を送信されるため、ループバック以外では暗号化する必要があります。方法は 2 つあります。サーバーをループバック（MCP_HOST=127.0.0.1）にバインドして、手前に配置したリバースプロキシ（Caddy/nginx）で TLS を終端する方法、または MCP_TLS_CERT と MCP_TLS_KEY に PEM 証明書／鍵のペアを設定して、サーバー自身に HTTPS を提供させる方法です。プレーン HTTP も引き続き完全にサポートされており、ゼロ設定のデフォルトです。ただし、ループバック以外にバインドして暗号化されていない HTTP でトークンを送信する場合、サーバーは起動時に警告をログに記録します。これを承知のうえで警告を抑制するには、MCP_ALLOW_PLAINTEXT=true を設定します。

トークンのローテーションと有効期限。 デフォルトでは、ベアラートークンに有効期限はありません。クライアントを切断せずにトークンをローテーションできる、組み合わせて使用可能な 2 つの任意の設定があります。

• 自動生成トークン — 生成されたトークンの有効期間を設定するには、MCP_AUTH_TOKEN_TTL_DAYS（小数の日数も指定可能）を設定します。サーバーは有効期限が切れる少し前に実行中に自動でローテーションします（再起動は不要です。サーバー停止中に期限が切れた場合は起動時にもローテーションします）。新しいトークンは stderr に出力され、置き換え直後のトークンも MCP_AUTH_TOKEN_GRACE_HOURS（デフォルトは 24）時間は引き続き有効として検証されるため、処理中のクライアントは切り替えを乗り越えられます。より早くローテーションするには、$CACHE_DIR/.env（またはその中の MCP_AUTH_TOKEN の行だけ）を削除して再起動します。
• 明示的なトークン — 自分で MCP_AUTH_TOKEN を設定した場合、有効期間の管理は自分で行います（TTL は適用されません）。ローテーションするには、新しいトークンを MCP_AUTH_TOKEN に設定し、古いトークンを MCP_AUTH_TOKEN_PREVIOUS に移してから再起動します。切り替え期間中は両方が受け付けられます。すべてのクライアントが新しいトークンに移行したら、MCP_AUTH_TOKEN_PREVIOUS を削除して再起動します。現在有効なすべてのトークンとの比較では、常にタイミングセーフな処理が行われます。

総当たり攻撃対策（fail2ban）。 自動生成トークンは 256 ビットのランダム値なので、推測は現実的に不可能です。自分で MCP_AUTH_TOKEN を設定する場合は、長くランダムな値にしてください（例：openssl rand -base64 32）。総当たり攻撃が問題になるのは、短いトークンや推測されやすいトークンを使う場合です。サーバー内では、失敗したログインのレート制限やロックアウトは行いません。その役割は、リクエストがサーバーに到達する前に送信元 IP を禁止する fail2ban のようなファイアウォールレベルのツールにあります。これを容易にするため、拒否されたリクエストはすべて、構造化されたログ行を stderr に出力します。

{"ts":"2026-06-18T17:28:00.370Z","level":"warn","msg":"auth_failed","client":"203.0.113.7","hadToken":true}

すぐに使える fail2ban 設定が fail2ban/ に含まれています。filter.d/ccu-mcp.conf を /etc/fail2ban/filter.d/ に、jail.d/ccu-mcp.local の jail を /etc/fail2ban/jail.d/ にコピーしてください（デフォルトでは、10 分間に 5 回失敗すると 1 時間禁止されます）。サーバーは stderr にログを出力するため、ログを収集している場所を fail2ban に指定します。ユニットとして実行する場合はジャーナル（backend = systemd）、stderr をリダイレクトする場合や docker logs を使う場合はファイルを指定します。どちらの設定も jail ファイルに記載されています。LOG_LEVEL=warn 以下が必要です（デフォルトの info で問題ありませんが、error では該当行が出力されません）。リバースプロキシの背後で実行する場合、ログに記録される IP はプロキシのものになるため、fail2ban はプロキシのアクセスログに対して実行してください。

CORS 対応は、@marcinn2 がフォーク marcinn2/debmatic-mcp で初めて実装しました。ありがとうございます！

HTTPS

CCU が HTTPS を使用している場合（自己署名証明書でも問題ありません）、次の環境変数を追加します。

CCU_HTTPS=true
CCU_PORT=443

サーバーは自己署名証明書を自動的に受け入れます。CCU には自己署名証明書が付属しているため、証明書の検証はデフォルトで無効になっています（検証なしで実行すると、サーバーは警告をログに出力します）。接続を実際に検証して MITM の隙をなくすには、次の 3 つの方法があります。

• フィンガープリントをピン留めする（自己署名の機器証明書に最も簡単な方法）：CCU_TLS_FINGERPRINT に証明書の SHA-256 を設定します（16 進数。コロンの有無は問いません）。CCU がまったく同じ証明書を提示しない場合、接続は拒否されます。次のコマンドで確認できます。

  echo | openssl s_client -connect "$CCU_HOST:443" 2>/dev/null | openssl x509 -noout -fingerprint -sha256
  

• CA／自己署名 PEM を信頼する：標準のチェーン検証を行うには、CCU_CA_CERT に証明書ファイルのパスを指定します。
• システムの信頼ストア：CCU に公的に信頼された証明書がある場合は、CCU_TLS_VERIFY=true を設定します。

CCU_TLS_FINGERPRINT は CCU_CA_CERT より優先され、CCU_CA_CERT は CCU_TLS_VERIFY より優先されます。

ccu-mcp init を使うと、フィンガープリントをピン留めできます。CCU が提示する証明書を表示し、確認後にフィンガープリントを env ファイルに書き込みます。また、ccu-mcp doctor は後でピン留めを再確認し、正当な証明書のローテーション後には更新を提案します。

設定

すべての設定は環境変数で行います。

変数	デフォルト	説明
CCU_HOST	必須	CCU のホスト名または IP アドレス
CCU_PASSWORD	必須	CCU の管理者パスワード。設定が必要ですが、パスワードのない機器（新規の OpenCCU など）では空にできます
CCU_USER	Admin	CCU のユーザー名
CCU_PORT	80	API ポート（HTTPS を使用する場合は 443）
CCU_HTTPS	false	HTTPS で接続します（自己署名証明書に対応）
CCU_TLS_VERIFY	false	CCU の TLS 証明書をシステムの信頼ストアと照合して検証します（公的に信頼された証明書の場合）
CCU_TLS_FINGERPRINT	未設定	SHA-256 フィンガープリント（16 進数。コロンは省略可）で CCU の自己署名リーフ証明書を固定します。他の TLS オプションより優先されます
CCU_CA_CERT	未設定	チェーン検証に使用する CCU の CA／自己署名 PEM のパス
CCU_TIMEOUT	10000	CCU リクエストのタイムアウト（ミリ秒）
CCU_SCRIPT_TIMEOUT	30000	HM Script の実行タイムアウト（ミリ秒）
LOG_LEVEL	info	error、warn、info、または debug
CACHE_DIR	/data	デバイスタイプのキャッシュとセッションの保存先
CACHE_TTL	86400	キャッシュの有効期間（秒、24 時間）
MCP_TRANSPORT	http	http または stdio（CLI の --stdio フラグがこの設定より優先されます）
MCP_PORT	3000	HTTP サーバーのポート（HTTP モードのみ）
MCP_AUTH_TOKEN	自動生成	HTTP モード用のベアラートークン。初回起動時に生成され、$CACHE_DIR/.env に保存されます
MCP_AUTH_TOKEN_PREVIOUS	未設定	ローテーションの重複期間中に MCP_AUTH_TOKEN とともに受け入れられる以前のベアラートークン。重複期間を終了するには、この値を削除して再起動してください。明示的なトークンを使用する場合のみ
MCP_AUTH_TOKEN_TTL_DAYS	未設定（有効期限なし）	自動生成トークンの有効期間（日数、小数可）。有効期限の直前にサーバーが実行時に自動ローテーションします（新しいトークンは stderr に通知されます）。MCP_AUTH_TOKEN が設定されている場合は無視されます
MCP_AUTH_TOKEN_GRACE_HOURS	24	自動ローテーション後、置き換えられたトークンが引き続き受け入れられる重複期間（時間）
MCP_ALLOWED_ORIGINS	未設定	ブラウザーのオリジンの許可リスト（カンマ区切り）。未設定の場合、クロスオリジンのブラウザーアクセスは許可されません（デフォルトで拒否）。許可リストのオリジンは Access-Control-Allow-Origin にそのまま反映されます（* は使用されません）。このリストは DNS リバインディングのオリジンチェックにも使用されます
MCP_ALLOWED_HOSTS	MCP ポートの localhost／127.0.0.1／[::1]	DNS リバインディング保護で受け入れる追加の Host 値（host:port をカンマ区切りで指定）。クライアントがサーバーへの接続に使うすべての名前／IP（プロキシ、コンテナーの DNS 名、サーバーの IP アドレスなど）を追加してください
MCP_HOST	未設定（すべてのインターフェース）	HTTP リスナーのバインドアドレス。ループバックに限定するには 127.0.0.1 を設定します（例：TLS 終端プロキシの背後で使用）。この設定により、平文通信に関する警告も抑制されます
MCP_TLS_CERT / MCP_TLS_KEY	未設定	PEM 証明書／キーのパス。MCP を HTTPS で直接提供するには両方を設定します。通常の HTTP を使用する場合は未設定のままにします。片方だけを設定すると設定エラーになります
MCP_ALLOW_PLAINTEXT	false	true に設定すると、ベアラートークンを通常の HTTP で提供することを承認し、非ループバックでの平文通信に関する警告を抑制します
CCU_RATE_LIMIT_BURST	20	CCU に送信するリクエストの最大バースト数
CCU_RATE_LIMIT_RATE	10	CCU へのリクエストの持続レート（毎秒）
RESOURCE_POLL_INTERVAL	60	MCP リソース変更通知のポーリング間隔（秒）

1 台のサーバーから複数の CCUを操作する場合、これらのフラットな CCU_* 変数は名前付きプロファイルに置き換えられます。詳しくは、以下の複数の CCU ターゲットを参照してください。

コマンドラインフラグ

ccu-mcp init           # interactive setup: probe the CCU, pin its TLS cert,
                       #   test the login, write an env file (default ./.env)
ccu-mcp doctor         # validate an env file end-to-end: reachability,
                       #   certificate pin, login, privilege level
ccu-mcp secret [prof]  # store ONE CCU password into an env file via a local
                       #   hidden prompt — name the target when the file
                       #   defines profiles, omit it for a single CCU (used by
                       #   the LLM-guided setup below; also the rotation path)
ccu-mcp --stdio        # serve over stdin/stdout (overrides MCP_TRANSPORT)
ccu-mcp --http         # serve over HTTP (default)
ccu-mcp --env <path>   # load configuration from a dotenv file (already-set
                       #   environment variables win); also accepted by
                       #   init/doctor/secret to pick the file they
                       #   write/check/update (default ./.env)
ccu-mcp --version      # print the installed version and exit
ccu-mcp --help         # print usage and exit

ccu-mcp init は、1 つ以上の CCU ターゲット（複数の CCU ターゲット）の設定を順に案内します。最初に複数のターゲットを設定するかどうかを尋ね、ターゲットごとに名前、エンドポイント、証明書のピン、認証情報、2 つのポリシーフラグを順に入力し、どのターゲットを最初に有効にするかを尋ねます。設定したユーザーが ADMIN レベルか USER レベルかを検出します（スクリプトベースのツールには ADMIN が必要です）。最後に、すぐに貼り付けられる MCP クライアント用の設定スニペットを表示します。事前に設定を用意する必要はありません。ccu-mcp doctor は、いずれかのチェックが失敗するとゼロ以外の終了コードを返すため、スクリプトでも使用できます。対話形式で実行すると、CCU の証明書が正当にローテーションされた場合に、ピンの更新を提案します。実行例：複数のターゲットを設定する。

LLM によるセットアップ（セットアップモード）

このウィザードには、会話形式のバージョンもあります。設定を始める前に、MCP クライアントにサーバーを登録してください。--stdio --env <path> を指定して起動し、設定がないか不完全な場合、サーバーはセットアップモードで起動します。ここでは、4 つの setup_* ツール（setup_status、setup_probe、setup_write_profile、setup_test）のみを公開する最小限の MCP サーバーと、LLM が通常のチャットで同じプローブ → ピン → ログインテスト → 書き込みの手順を案内するための指示が提供されます。

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": ["ccu-mcp", "--stdio", "--env", "/path/to/.env"]
    }
  }
}

あとは「CCU 接続をセットアップして」と頼むだけです。ただし、意図的に設けられた例外が 1 つあります。パスワードがモデルやチャットの記録を通じて送信されることはありません。setup_write_profile にパスワードのパラメーターはありません。代わりに、アシスタントからターミナルで実行するワンライナーが提示されます。npx ccu-mcp secret <profile> --env /path/to/.env、またはインストール方法に応じた同等のコマンドを実行すると、入力内容を表示せずにローカルでパスワードを求め、ファイルにパスワードのみを書き込みます（モード 0600）。このコマンドではなく、ツールが出力したコマンドをコピーしてください。出力したビルド名が指定されるため、このサブコマンドを持たない古いインストール先に誤って実行されることはありません。setup_test が成功を報告したら、MCP サーバーを再接続してください。同じクライアント設定で、完全に設定された状態で起動します。

ここでも複数の CCU を設定できます。「prod と dev の CCU があります」のように伝えると、アシスタントはターゲットごとにプローブ → 書き込み → シークレットの手順を繰り返します。setup_write_profile は name（および protected、readonly、makeDefault）を受け取り、指定したターゲットだけをアップサートし、ほかのターゲットと保存済みのパスワードを維持します。各ターゲットに対して、それぞれ ccu-mcp secret <name> を実行する必要があります。設定したすべてのターゲットにパスワードが設定されるまで、サーバーはセットアップモードのままです。途中で再接続すると、まだパスワードが設定されていないターゲットの名前と、設定を完了するための正確な secret コマンドが表示され、再びセットアップモードになります。CCU に実際にパスワードがない場合は、パスワードの設定漏れではありません。意図的にそう指定するには、キーに空の値を書き込みます（CCU_<NAME>_PASSWORD=）。

セットアップモードは stdio 専用です（設定ファイルを書き込む未設定の HTTP エンドポイントは、許容できない攻撃対象領域になります）。また、--env を指定せずに起動すると、セットアップツールを黙って提供するのではなく、明確にエラーになります。

--version と --help は設定不要です。更新後などに、インストール済みのコピーの実態を確認するには、次のように使います。

$ npx ccu-mcp@latest --version
1.10.0

npx ccu-mcp をそのまま実行すると、レジストリを再確認せずに ~/.npm/_npx にキャッシュされたコピーが再利用される点に注意してください。最新リリースを使う場合は、@latest を指定するか、そのキャッシュを削除してください。

これらを指定する方法（インライン、.env、または export）

必須の CCU_HOST／CCU_PASSWORD（およびその他すべて）は環境変数です。次のいずれかの方法で指定してください。いずれか1つで十分です。

• .mcp.json にインラインで指定 — 上記のオプション Aにある env ブロックを使います。最も簡単で、設定が1か所にまとまります。

• シェルで export — 上記のクイックスタートの例を参照してください。

• .env ファイル — シークレットを .mcp.json に含めずに済みます。サーバー独自の --env フラグで渡してください（ccu-mcp init が作成し、表示するスニペットでもこの方法を使います）。

  {
    "mcpServers": {
      "ccu-mcp": {
        "command": "npx",
        "args": ["ccu-mcp", "--stdio", "--env", "/path/to/.env"]
      }
    }
  }
  

  （スクリプトパスの前に Node 独自の --env-file= フラグを指定する方法も使えますが、そのファイルがまだ存在しない場合、node は起動を拒否します。また、dist/index.js へのフルパスが必要です。）

  .env.example を .env にコピーし、値を記入してください（すべての変数について説明されています）。Docker を使う場合は、同じファイルを docker run --env-file .env または compose の env_file: で渡せます。.env は Git の追跡対象から除外してください。

複数の CCU ターゲット（プロファイル）

デフォルトでは、上記の CCU_* 変数は単一の CCU を設定します。1つのサーバーから複数の CCU（例：本番環境 + 開発環境）に接続するには、代わりに名前付きプロファイルを定義します。ほかの設定と同じ方法（インライン、.env、または export — 上記を参照）で設定してください。

CCU_PROFILES=prod,dev
CCU_DEFAULT_PROFILE=prod           # active at startup (defaults to the first listed)

CCU_PROD_HOST=ccu.example
CCU_PROD_USER=ai
CCU_PROD_PASSWORD=...
CCU_PROD_HTTPS=true
CCU_PROD_PROTECTED=true            # writes need confirm:true

CCU_DEV_HOST=127.0.0.1
CCU_DEV_PORT=18080
CCU_DEV_USER=Admin
CCU_DEV_PASSWORD=                  # may be empty (e.g. an OpenCCU dev box)

各プロファイルには、フラットな変数と同じ設定を指定します。変数名の先頭に CCU_<NAME>_ を付けます（名前は大文字にし、英数字以外は _ に置き換えます）。設定項目は HOST（必須）、PASSWORD（空でもかまいません。フラットな CCU_PASSWORD と異なり、省略した場合も空として扱われます）、USER、PORT、HTTPS、TIMEOUT、SCRIPT_TIMEOUT、TLS_FINGERPRINT、CA_CERT、TLS_VERIFY に加え、次の2つのポリシーフラグがあります。

• CCU_<NAME>_PROTECTED=true — confirm: true を指定して呼び出さない限り、書き込みツールは拒否されます。指定すると、そのセッションが続く間、そのターゲットへの書き込みが許可されます。例外として、run_script と delete_system_variable では呼び出しのたびに confirm: true が必要です（スクリプトは型付きツールのすべてのガードを迂回し、削除は取り消せないため、セッションのロック解除は適用されません）。また、これらを確認しても、ほかの書き込みに対するセッションのロックは解除されません。
• CCU_<NAME>_READONLY=true — 書き込みツールは無条件に拒否されます。

CCU_PROFILES が未設定の場合は、フラットな CCU_* 変数が単一の default プロファイルとして使われます（動作に変更はありません）。実行時には、list_ccu_targets でターゲットを確認でき、get_connection_info でアクティブなターゲットを確認でき、use_ccu で切り替えられます。読み取りツールでは target も任意で指定できます。これにより、切り替えずに1回の呼び出しだけ別の CCU から読み取れます。

複数のターゲットを設定する

ウィザードを使用する場合。 ccu-mcp init は最初に質問し、ターゲットごとに名前 → エンドポイント → 証明書のピン留め → 認証情報 → ポリシーフラグの順に入力を繰り返し、最後に どのターゲットをアクティブな状態で開始するかを尋ねます。

$ npx ccu-mcp init --env ~/.config/ccu-mcp/.env
ccu-mcp setup — probes your CCU, pins its TLS certificate, tests the
login, and writes the result to /home/you/.config/ccu-mcp/.env.

Set up multiple CCU targets (e.g. prod/dev)? [y/N]: y
Profile name [prod]: prod
CCU hostname or IP: ccu.example
Probing ccu.example ...
  Found the CCU API on port 443 (HTTPS).
Use HTTPS? [Y/n]: y
Port [443]: 443
The CCU presents this TLS certificate:
  Subject: ccu.example
  Issuer:  ccu.example
  Valid:   Jun 19 21:37:09 2026 GMT — Jun 16 21:37:09 2036 GMT
  SHA-256: 90:0C:4C:F2:53:22:E7:78:...:40:ED:16:95:6E:BB:B1:53
Pin this certificate's fingerprint (recommended)? [Y/n]: y
CCU user [Admin]: ai
CCU password (input hidden):
Testing login ...
  Login OK (CCU 3.87.6.20260614) — privilege level ADMIN: all tools available.
Protect this target (write tools then require confirm:true)? [y/N]: y
Make this target read-only (write tools refused entirely)? [y/N]: n
Add another CCU target? [y/N]: y
Profile name: dev
CCU hostname or IP: 192.168.1.50
Probing 192.168.1.50 ...
  Found the CCU API on port 80 (HTTP).
Use HTTPS? [Y/n]: n
Port [80]: 80
CCU user [Admin]: Admin
CCU password (input hidden):
Testing login ...
  Login OK (CCU 3.87.6.20260614) — privilege level ADMIN: all tools available.
Protect this target (write tools then require confirm:true)? [y/N]: n
Make this target read-only (write tools refused entirely)? [y/N]: n
Add another CCU target? [y/N]: n
Default target (prod/dev) [prod]: prod

Wrote /home/you/.config/ccu-mcp/.env (mode 0600).

書き込まれるファイルはプロファイル形式で、ターゲットごとにコメント付きのブロックが1つずつあります。ウィザードが書き換えるのはこれらのキーだけなので、ファイル内のそれ以外の設定（LOG_LEVEL、 CACHE_DIR、MCP_*）は保持されます。

# Written by ccu-mcp setup — https://github.com/claymore666/ccu-mcp#configuration
CCU_PROFILES=prod,dev
CCU_DEFAULT_PROFILE=prod

# --- target: prod ---
CCU_PROD_HOST=ccu.example
CCU_PROD_PORT=443
CCU_PROD_HTTPS=true
CCU_PROD_USER=ai
CCU_PROD_PASSWORD="..."
CCU_PROD_TLS_FINGERPRINT=90:0C:4C:F2:53:22:E7:78:...:40:ED:16:95:6E:BB:B1:53
CCU_PROD_PROTECTED=true

# --- target: dev ---
CCU_DEV_HOST=192.168.1.50
CCU_DEV_PORT=80
CCU_DEV_HTTPS=false
CCU_DEV_USER=Admin
CCU_DEV_PASSWORD=""

既存のファイルに対して init を再実行すると、これらの設定を置き換えるかどうかを尋ねられます。3つ目のターゲットを追加するにはリスト全体をもう一度入力する必要があるため、1回限りの追加ならファイルを編集するか（または単一のターゲットを追加・更新する setup_write_profile を使用して）、その後 doctor を実行してください。

ターゲットごとに1つのパスワード。 ccu-mcp secret が書き込むキーは常に1つだけなので、ターゲット名を指定します。init ではパスワードをその場で入力しますが、 LLM ガイド付きフローと、その後のパスワード変更はすべて secret を使用します。プロファイルファイルに対して名前を指定せずに実行すると、必要な操作が一覧表示されます。

$ ccu-mcp secret --env ~/.config/ccu-mcp/.env
This file configures named targets (prod, dev) — one password each:
  node /home/you/.local/bin/ccu-mcp secret prod --env /home/you/.config/ccu-mcp/.env
  node /home/you/.local/bin/ccu-mcp secret dev --env /home/you/.config/ccu-mcp/.env

$ ccu-mcp secret prod --env ~/.config/ccu-mcp/.env
CCU password for [email protected] (input hidden):
Wrote CCU_PROD_PASSWORD to /home/you/.config/ccu-mcp/.env (mode 0600).

これらのヒントが意図的に ccu-mcp ではなく node <path> と表示されるのは、パスがヒントを出力したビルドを指しているためです。その行をコピーしても、このサブコマンドがない古いコピーで実行されることはありません。secret はフラットな単一 CCU ファイルに対する名前指定を拒否し、プロファイルファイルに対する不明な名前も拒否するため、誤ったキーを書き込むことはありません。

すべてを一度に検証する。 doctor はすべてのターゲットについて、設定、到達可能性、ピン、ログイン、権限レベルを確認し、いずれかのチェックに失敗するとゼロ以外の終了コードを返します。

$ ccu-mcp doctor --env ~/.config/ccu-mcp/.env
ccu-mcp doctor — checking /home/you/.config/ccu-mcp/.env
  ✓ configuration loads: 2 target(s), default "prod"

Target "prod" — ccu.example:443 (HTTPS)
  ✓ CCU API reachable
  ✓ pinned TLS fingerprint matches the presented certificate
  ✓ login OK as "ai" (CCU 3.87.6.20260614) — privilege level ADMIN

Target "dev" — 192.168.1.50:80 (HTTP)
  ✓ CCU API reachable
  ✓ login OK as "Admin" (CCU 3.87.6.20260614) — privilege level ADMIN

All checks passed.

クライアントで使用する場合。 1つの MCP サーバーエントリですべてのターゲットを利用できます。--env ファイルにターゲット一覧が含まれるため、CCU を追加してもクライアント設定を変更する必要はありません。

{
  "mcpServers": {
    "ccu-mcp": {
      "command": "npx",
      "args": ["ccu-mcp", "--stdio", "--env", "/home/you/.config/ccu-mcp/.env"]
    }
  }
}

その後、チャットで「設定されている CCU はどれですか？」（list_ccu_targets）、「dev のリビングルームの温度を読み取って」（target: "dev" を指定した1回の呼び出し）、「dev に切り替えて」（use_ccu）と指示できます。上記のように CCU_PROD_PROTECTED=true に設定している場合、prod に対する最初の書き込みでは confirm: true を求められ、それによってそのターゲットはセッションの残りの間、ロックが解除されます。ただし、run_script と delete_system_variable は毎回確認を求めます。

設定エラー

一部の間違いは無視されず、サーバーの起動を停止させます。これらは放置すると、気づかれないままかなり後になって問題が発生するため、意図的に終了するようになっています。ccu-mcp doctor は、サーバーを起動せずに環境ファイルに対して同じエラーを報告し、到達可能性、証明書のピン留め、ログインなどのライブチェックも行います。 例外は、--stdio --env <path> を指定して起動した場合です。設定に問題があると終了するのではなく、セットアップモード（エラーはサーバーの指示に表示されます）に入り、会話を通じて修正できるようになります。

メッセージ	原因と致命的な理由
CCU_HOST environment variable is required	CCU が設定されていません（CCU_PROFILES も未設定です）。
CCU_PASSWORD environment variable is required	変数が存在しません。空の値は受け付けられます（新しい OpenCCU ボックスには Admin パスワードがありません）。そのため、これは「まだ設定されていない」ことを意味します。ccu-mcp secret でパスワードを保存するまで、単一 CCU のセットアップモードサーバーがセットアップモードを維持するのはこのためです。
no password stored yet for target <name>	プロファイル形式における同等のエラーで、セットアップモードに限られます。CCU_<NAME>_PASSWORD が存在しません。読み込み済みの設定では、存在しないキーは引き続き空として扱われます（変更なし。これにより OpenCCU の開発用ターゲットが引き続き動作します）。ただし、セットアップが完了したかを判断する際には、存在しないことは「まだ入力されていない」ことを意味します。そのためサーバーはセットアップモードを維持し、完了させるための ccu-mcp secret <name> の実行方法を表示します。空のパスワードを意図的に指定するには、CCU_<NAME>_PASSWORD= を記述してください。
CCU_DEFAULT_PROFILE is set but CCU_PROFILES is not	プロファイル設定の残りです。これを無視すると、環境ファイルでは名前付きターゲットを示しているのに、書き込み先がフラットな CCU_HOST のボックスになります。
CCU_PROFILES is set but lists no profile names	空の値、またはコンマのみの値です。
CCU_PROFILES lists "<name>" more than once	プロファイル名が重複しています。
... both map to the same env prefix CCU_<P>_* — rename one	異なる名前でも、サニタイズ後に衝突することがあります。prod-a と prod.a はどちらも CCU_PROD_A_* を読み取るため、気づかないまま同じターゲットになります。
CCU_DEFAULT_PROFILE="x" is not one of CCU_PROFILES (...)	起動プロファイルの入力ミスです。
profile "<name>" is missing CCU_<P>_HOST	すべてのプロファイルにホストが必要です。パスワードは空でもかまいません。
TLS_FINGERPRINT/CA_CERT/TLS_VERIFY is set but HTTPS is disabled	検証コードの経路は HTTPS でのみ使用できます。これらを無視すると、認証情報が平文で送信されているのに、接続が検証済みだと思い込むことになります。CCU_HTTPS=true（または CCU_<NAME>_HTTPS=true）を設定するか、これらを削除してください。
MCP_TLS_CERT and MCP_TLS_KEY must both be set (or both unset)	TLS 設定の片方だけでは HTTPS を提供できません。
MCP_TRANSPORT must be "http" or "stdio"	大文字と小文字は区別されます。STDIO のような入力ミスが黙って HTTP を選び、stdio を起動するクライアントをいつまでも待たせることがないようにしています。
<VAR> must be a positive integer	ポート、タイムアウト、CACHE_TTL、レート制限、RESOURCE_POLL_INTERVAL が該当します。値全体が数字である必要があります。CCU_TIMEOUT=30s は 30 ミリ秒として読み取られず、拒否されます。また、30.5 や 1e4 も切り捨てられずに拒否されます。
<VAR> must be a positive number	小数値に意味がある、2 つの期間設定 MCP_AUTH_TOKEN_TTL_DAYS と MCP_AUTH_TOKEN_GRACE_HOURS が該当します。
<VAR> must be "true" or "false"	すべてのブール値設定（CCU_HTTPS、CCU_TLS_VERIFY、CCU_<NAME>_PROTECTED、CCU_<NAME>_READONLY、MCP_ALLOW_PLAINTEXT）が該当します。前後の空白や大文字・小文字は問題ありませんが、yes、1、on は使えません。これらをfalseとして扱うと、保護機能が気づかないうちに無効になるためです。
CCU_CA_CERT could not be read	パスが間違っているか、サーバーの実行ユーザーが読み取れません。

設定を修正している間も、ccu-mcp --version と --help は設定なしで使用できます。

ツール

実際に行いたい作業に応じて整理された28個のツール：

デバイスを探す — list_devices、list_rooms、list_functions、list_interfaces、list_programs、list_system_variables、list_links、describe_device_type

状態を読み取る — get_value、get_values（一括）、get_paramset

変更する — set_value、put_paramset、set_system_variable、create_system_variable、delete_system_variable、assign_channel、unassign_channel、execute_program

状態を確認する — get_service_messages、acknowledge_service_messages、get_rssi、get_system_info

接続先を切り替える — list_ccu_targets、get_connection_info、use_ccu（複数CCUプロファイル。上記を参照）

その他 — help（状況に応じたヘルプ）、run_script（一括操作、デバイスやチャンネルの名前変更、部屋への所属確認、または他のツールでは対応できない操作のための、生のHomeMatic Script）

ほとんどのツールはデバイスアドレスからインターフェースと値の型を自動判別するため、デバイスがBidCos-RFとHmIP-RFのどちらを使用しているかを知っておく必要はありません。

リソースとプロンプト

ツールに加えて、このサーバーはMCP リソースも公開します。クライアントがコンテキストとして添付できる、閲覧可能なJSONスナップショットです。

homematic://devices、homematic://rooms、homematic://functions、homematic://programs、homematic://sysvars、homematic://interfaces、homematic://device-types、homematic://system

サーバーはバックグラウンドでCCUをポーリングし（RESOURCE_POLL_INTERVAL秒ごと）、内容が変更されたリソースについてnotifications/resources/updatedを送信します。送信先はresources/subscribeでそのリソースを購読しているクライアントです。

また、MCP プロンプトも提供します。対応クライアントから呼び出せる、すぐに使えるワークフローです（例：Claude Codeのスラッシュコマンドとして）。

• check-windows — 窓やドアが開いていないか確認します
• room-status — 指定した部屋の詳細な状態レポート
• set-heating — 部屋の目標温度を設定します
• good-night — 夜間に備えて家を準備します
• diagnostics — デバイスの問題を確認します
• device-info — デバイスの機能とパラメーターに関する詳細情報

room引数とdevice引数はオートコンプリートに対応しています。completion/completeに対応したクライアントでは、このCCUに実際に登録されている部屋名とデバイス名が候補として表示されるため、WebUIでの部屋名の表記を覚えておく必要はありません。

MCPプロトコルのリビジョン

このサーバーはリビジョン**2025-11-25**を実装しており、古いクライアント向けには下位バージョンでネゴシエーションします（2025-06-18、2025-03-26、2024-11-05はいずれも受け入れられます）。特定のクライアントバージョンは必要ありません。tools、resources（subscribeを含む）、prompts、completions、loggingをサポートすると通知します。

リビジョン2026-07-28（リクエストごとのプロトコルバージョン、server/discover）はまだ実装されていません。執筆時点では、このサーバーの構築に使用しているTypeScript SDKが対応しておらず、このサーバーはSDKに準拠しています。

動作の仕組み

このサーバーは、CCUのJSON-RPC API（WebUIと同じAPI）を使用します。起動時には、次の処理を行います。

1. ログインしてセッションをキャッシュします（再起動後も再利用されます）
2. ディスクからデバイスタイプのキャッシュを読み込みます（またはバックグラウンドでキャッシュを作成します）
3. stdioまたはHTTPでMCPサーバーを起動します

デバイスタイプのスキーマはローカルにキャッシュされるため、AIはCCUに毎回アクセスすることなく、有効なパラメーター、型、値の範囲を確認できます。

値はネイティブ型で返されます。"21.500000"ではなく21.5、"true"ではなくtrueです。

テスト済みデバイス

以下のデバイスを使用した本番環境のdebmaticインストール環境でテスト済みです。

• HmIP-eTRV-2 / eTRV-2 I9F（ラジエーター用サーモスタット）
• HmIP-STHD（湿度センサー付き壁掛けサーモスタット）
• HmIP-WTH-2（壁掛けサーモスタット）
• HmIP-SWDO-I（ドア／窓センサー）
• HmIP-STHO（屋外温度／湿度センサー）
• HmIP-ESI（電力／ガスメーター）
• HmIP-FALMOT-C12（床暖房コントローラー）
• HmIP-HEATING（仮想暖房グループ）
• HmIP-WRCC2（壁掛けリモコン）
• HM-PB-6-WM55（BidCos 6ボタンリモコン）
• RPI-RF-MOD（無線モジュール）

他のデバイスタイプも動作するはずです。このサーバーは静的なデバイスデータベースを維持するのではなく、CCUに問い合わせてパラメーターの説明を取得します。

変更履歴

リリースノート（アップグレード前に確認すべき動作の変更を含みます。 設定検証の厳格化、/health のレスポンス形式、セッションごとの書き込み確認、 再試行の動作）は、CHANGELOG.md に記載されています。

ヘルプの利用と貢献

• 不具合や機能のアイデアがありますか？ イシューを作成してください： github.com/claymore666/ccu-mcp/issues
• 質問、セットアップのサポート、HomeMatic に関する一般的な話題ですか？ HomeMatic forum をご利用ください。メンテナーは claymore666 としてフォーラムを確認しています。
• セキュリティ上の問題を見つけましたか？ 公開の場には投稿しないでください。 非公開での報告については SECURITY.md をご覧ください。
• パッチを送りたいですか？ CONTRIBUTING.md では、セットアップ、 対象ブランチ、コーディング規約、テスト方針について説明しています。

参加するすべての方には、 行動規範に従っていただきます。

プロジェクトのドキュメント

ドキュメント	内容
ROADMAP.md	プロジェクトの今後の方向性と、意図的に対応しないこと
GOVERNANCE.md	意思決定者と、既知の継続性に関する課題
SECURITY.md	報告方法、セキュリティ要件、脅威モデル
docs/architecture.md	全体的な設計とリクエストの流れ
docs/assurance-case.md	証拠に基づくセキュリティ要件の根拠
CHANGELOG.md	各リリースでの変更点

関連プロジェクト

• OpenCCU — Raspberry Pi、x86/ARM、CCU3/ELV-Charly ハードウェア向けの、コミュニティが保守するクラウド不要の CCU ファームウェア（旧 RaspberryMatic。OCCU フレームワークを基盤に構築）
• debmatic — Debian、Ubuntu、Raspberry Pi OS、Armbian で HomeMatic を実行
• OCCU — eQ-3 が開発したオリジナルの Open CCU SDK（HomeMatic の上流ソフトウェア）。現在はコミュニティが保守する OpenCCU に置き換えられつつあります
• MCP — Model Context Protocol の仕様
• Mathias (mdzio) による ccu-ai-mcp — HomeMatic 向けの、同じ志を持つ MCP サーバーです。意図的に異なる、洗練されたアプローチ（ユーザー定義の HM-Script ツールを備えた軽量な Go コア）を採用しています。HomeMatic forum の紹介記事をご覧ください。

ライセンス

MIT