Goodwe Inverter Mcp Server

GoodWe インバーター MCP サーバー

ローカルネットワーク経由でGoodWe ソーラーインバーターを監視、制御する MCP サーバーです。

goodwe ライブラリと Model Context Protocol Python SDK を基盤としています。

基盤として、Home Assistant GoodWe integration を使用しています。センサーの定義、動作モード、設定、インバーターファミリーのサポートは、この実装に直接基づいています。

機能

• PV 発電量、バッテリーの状態、系統からの電力の輸入・輸出、負荷消費量などのリアルタイムデータを読み取ります
• 設定可能なすべてのインバーター設定を読み書きします
• 動作モードを切り替えます（一般、エコ、バックアップ、ピークシェービング、オフグリッドなど）
• 系統への電力輸出制限とバッテリーの放電深度を制御します
• 7 つの MCP リソース：ステータス、稼働時データ、設定、電力フロー、日別エネルギー、バッテリー、センサーカタログ
• 一般的なワークフロー向けの組み込みプロンプトテンプレート 6 種（ステータス概要、診断、最適化など）
• すべての HTTP トランスポートで Bearer トークン認証に対応
• 4 種類のトランスポートモード：stdio、SSE、Streamable HTTP、server（SSE と Streamable HTTP の組み合わせ）
• 環境変数による自動接続

要件

• Python 3.10+
• ローカルネットワークから到達可能な GoodWe インバーター（UDP ポート 8899 または Modbus/TCP ポート 502）

インストール

# with uv (recommended) — installs the locked dependency set from uv.lock
uv sync

# or a plain (editable) install
uv pip install -e .

使用方法

stdio（Claude Desktop）

goodwe-mcp

~/.claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "goodwe": {
      "command": "goodwe-mcp",
      "env": {
        "GOODWE_HOST": "192.168.1.100"
      }
    }
  }
}

SSE トランスポート

goodwe-mcp --transport sse --port 8080
# Server listens on http://0.0.0.0:8080/sse

Streamable HTTP トランスポート

goodwe-mcp --transport streamable-http --port 8080
# Server listens on http://0.0.0.0:8080/mcp

Server トランスポート（SSE と Streamable HTTP の組み合わせ）

両方のトランスポートを単一ポートで提供します。レガシーな SSE クライアントと最新の Streamable HTTP クライアントの両方に同時に対応する必要がある場合に便利です。

goodwe-mcp --transport server --host 0.0.0.0 --port 8080
# SSE:             http://0.0.0.0:8080/sse  (GET) and /messages/ (POST)
# Streamable HTTP: http://0.0.0.0:8080/mcp

オプション

--transport {stdio,sse,streamable-http,server}   Transport mode (default: stdio)
--host HOST                                      Bind address for SSE/HTTP (default: 127.0.0.1)
--port PORT                                      Listen port for SSE/HTTP (default: 8000)
--log-level {DEBUG,INFO,WARNING,ERROR}           Logging verbosity (default: INFO)
--auth-token TOKEN                               Bearer token required on all HTTP requests (env: MCP_AUTH_TOKEN)
--base-url URL                                   Public base URL, e.g. https://mcp.example.com (env: MCP_BASE_URL)
--allowed-hosts HOSTS                            Comma-separated Host header values to accept (env: MCP_ALLOWED_HOSTS)
--allowed-origins ORIGINS                        Comma-separated Origin header values to accept (env: MCP_ALLOWED_ORIGINS)

環境変数

変数	説明	デフォルト
GOODWE_HOST	起動時の自動接続に使用するインバーターの IP アドレス／ホスト名	—
GOODWE_PORT	インバーターの UDP/TCP ポート	8899
GOODWE_FAMILY	インバーターファミリーの上書き設定（ET、EH、BT、BH、ES、EM、BP、DT、MS、NS、XS）	自動検出
MCP_AUTH_TOKEN	すべての HTTP リクエストで必要な Bearer トークン	—（認証無効）
MCP_BASE_URL	サーバーの公開ベース URL（OAuth 発行者 URL として使用）	http://<host>:<port>
MCP_ALLOWED_HOSTS	許可する Host ヘッダー値（カンマ区切り）。ループバック以外へのバインド時に DNS リバインディング保護を有効にします	—（保護はループバックへのバインド時のみ）
MCP_ALLOWED_ORIGINS	許可する Origin ヘッダー値（カンマ区切り、ブラウザベースのクライアント用）	—
MCP_PORT	コンテナーのデフォルトコマンドとヘルスチェックで使用する待ち受けポート（Docker のみ）	8000

認証

すべての HTTP トランスポート（sse、streamable-http、server）で Bearer トークン認証に対応しています。 有効にすると、すべての MCP リクエストに Authorization: Bearer <token> ヘッダーが必要です。 /health エンドポイントは常に認証の対象外で、Kubernetes のプローブは引き続き動作します。

環境変数で有効にする（推奨）

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
goodwe-mcp --transport server --host 0.0.0.0 --port 8080

CLI フラグで有効にする

goodwe-mcp --transport streamable-http --port 8080 --auth-token my-secret-token

Claude Desktop／MCP クライアントの設定

クライアントの MCP サーバー設定にトークンを追加します。たとえば、ヘッダーを挿入するプロキシ経由で streamable-http トランスポートを使う Claude Desktop や、Authorization ヘッダーに対応するクライアントの場合は、次のように設定します。

{
  "mcpServers": {
    "goodwe": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    }
  }
}

Docker／Docker Compose

トークンを環境変数として渡します：

MCP_AUTH_TOKEN=my-secret-token GOODWE_HOST=192.168.1.100 \
  docker compose -f docs/docker-compose.yml up -d

Kubernetes

マニフェストを適用する前に、docs/k8s/secret.yaml にトークンを設定します：

stringData:
  GOODWE_HOST: "192.168.1.100"
  MCP_AUTH_TOKEN: "my-secret-token"

MCP_AUTH_TOKEN が空、または設定されていない場合、認証は無効になり、すべての HTTP エンドポイントが公開されます。トークンを設定せずにループバック以外のアドレスにバインドすると、サーバーは起動時に警告をログに記録します。

DNS リバインディング保護

サーバーがループバックアドレスにバインドされている場合、MCP SDK は Host ヘッダーと Origin ヘッダーを自動的に検証します。それ以外のアドレス（Docker のデフォルトである 0.0.0.0 を含む）にバインドする場合は、クライアントがサーバーへの接続に正当に使用するホスト名または host:port の組み合わせを列挙してください。

MCP_ALLOWED_HOSTS="mcp.example.com,192.168.1.10:8000" \
  goodwe-mcp --transport server --host 0.0.0.0 --port 8000

列挙されていない Host ヘッダーを含むリクエストは、HTTP 421 で拒否されます。:* サフィックスを使うと、任意のポートに一致します（例：192.168.1.10:*）。MCP_ALLOWED_ORIGINS を使うと、特定のオリジンからのブラウザベースのクライアントも許可できます。この設定がない状態で非ループバックアドレスにバインドすると、サーバーは起動時に警告をログに記録します。

TLS / HTTPS

MCP サーバー自体は TLS を終端しません。ローカルホスト以外にデプロイする場合は、TLS を終端するリバースプロキシ（nginx、Caddy、Traefik）を前段に配置してください。インバーターのデータは、世帯に関連付けられると GDPR 上の個人データに該当するため、平文 HTTP で提供することはセキュリティリスクです。

Caddy を使用した例（最も簡単な方法）：

mcp.example.com {
    reverse_proxy localhost:8000
}

データ処理に関する通知

このサーバーは、インバーターの IP アドレス、シリアル番号、エネルギー消費量の指標など、GoodWe ソーラーインバーターからのデータを処理します。家庭に設置し、所有者が個人利用のために運用する場合、この処理は GDPR の家庭内適用除外（第 2 条第 2 項（c））に該当し、GDPR は適用されません。商用目的でデプロイする場合（たとえば、第三者の顧客が所有するインバーターを監視する場合）、運用者は GDPR（EU）2016/679 に基づくデータ管理者となり、処理の適法な根拠（第 6 条）を確立し、処理活動の記録（第 30 条）を維持し、TLS 暗号化やアクセス制御を含む適切な技術的・組織的対策（第 32 条）を確実に講じる必要があります。

Docker

ビルド

現在のマシンのアーキテクチャ向けにビルドします。

docker build -t goodwe-inverter-mcp:latest .

マルチプラットフォームビルド（amd64 + arm64）

docker buildx を使用して、x86-64 サーバーと ARM ボード（Raspberry Pi、Apple Silicon、AWS Graviton など）の両方で動作するイメージを作成します。

初回のみの設定 — クロスコンパイルに対応したビルダーを作成します。

docker buildx create --name multi --driver docker-container --bootstrap --use

両方のプラットフォーム向けにビルドしてローカルデーモンに読み込む — containerd イメージストアが必要です（Docker Desktop 4.34 以降ではデフォルトで有効です。Linux では dockerd --snapshotter=overlayfs を実行するか、/etc/docker/daemon.json で有効にしてください）。

docker buildx build --platform linux/amd64,linux/arm64 -t goodwe-inverter-mcp:latest --load .

両方のプラットフォーム向けにビルドしてレジストリにプッシュする（例：Docker Hub または GHCR）：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t youruser/goodwe-inverter-mcp:latest \
  --push .

両方のプラットフォーム向けにビルドしてローカルの OCI tar としてエクスポートする（レジストリは不要です）：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t goodwe-inverter-mcp:latest \
  --output type=oci,dest=goodwe-inverter-mcp.tar .

実行

docker run -d \
  --name goodwe-mcp \
  -e GOODWE_HOST=192.168.1.100 \
  -p 8000:8000 \
  goodwe-inverter-mcp:latest

コンテナのデフォルトは --transport server（ポート 8000 での SSE + Streamable HTTP）です。

組み込みのヘルスチェックがポートの変更に追従するよう、MCP_PORT でポートを変更してください。

docker run -d -e GOODWE_HOST=192.168.1.100 -e MCP_PORT=9000 -p 9000:9000 \
  goodwe-inverter-mcp:latest

トランスポートを変更するには、コマンドを上書きしてください。ヘルスチェックのプローブ先にも反映されるよう、MCP_PORT も同期してください。

docker run -d -e GOODWE_HOST=192.168.1.100 -e MCP_PORT=9000 -p 9000:9000 \
  goodwe-inverter-mcp:latest \
  goodwe-mcp --transport streamable-http --host 0.0.0.0 --port 9000

Docker Compose

GOODWE_HOST=192.168.1.100 docker compose -f docs/docker-compose.yml up -d

docs/docker-compose.yml は、コンテナがローカル LAN 上のインバーターに接続できるよう、デフォルトで network_mode: host を使用します。ネットワークで LAN トラフィックがすでにコンテナにルーティングされている場合は、この行を削除してください。

Kubernetes

前提条件

GoodWe インバーターは、ローカルネットワーク上で UDP/TCP を介して通信します。Pod からインバーターの IP に接続できる必要があります。最も簡単な設定は、同じサブネット上のノードで hostNetwork: true を使用することです。クラスターがフラットネットワークまたは別のルーティング方式を使用している場合は、削除してください。

デプロイ

# 1. Edit the inverter IP
vi docs/k8s/secret.yaml

# 2. Apply all manifests
kubectl apply -f docs/k8s/

# 3. Check status
kubectl rollout status deployment/goodwe-mcp
kubectl logs -f deployment/goodwe-mcp

ヘルスエンドポイント

liveness と readiness の両プローブは GET /health にアクセスし、次の内容を返します。

{ "status": "ok", "inverter_connected": true }

HTTP サーバーが起動すると、Pod は準備完了になります。サーバーがインバーターへの接続に成功するまで、inverter_connected は false です（自動接続は最初の MCP クライアントセッションで実行されます）。

ツール

ツール	説明
connect_inverter	IP アドレス／ホスト名を指定して GoodWe インバーターに接続します
get_connection_status	接続状態を確認し、デバイス情報を表示します
get_device_info	モデル名、シリアル番号、ファームウェアのバージョンを表示します
get_runtime_data	すべてのライブセンサー値を取得します（種類での絞り込みは任意：PV/AC/BAT/GRID/UPS/BMS）
list_sensors	すべてのセンサー ID と名前を一覧表示します
read_sensor	ID を指定して単一のセンサーを読み取ります
get_settings_data	すべての設定可能な項目と現在の値を取得します
read_setting	ID を指定して単一の設定項目を読み取ります
write_setting	設定可能な項目に値を書き込みます
get_operation_mode	現在のモードとサポートされているモードを取得します
set_operation_mode	モードを設定します：general、eco、backup、off_grid、peak_shaving、eco_charge、eco_discharge
get_grid_export_limit	系統への売電上限（ワット）を取得します
set_grid_export_limit	系統への売電上限を設定します（0 = 無効）
get_battery_dod	バッテリーの放電深度設定を取得します
set_battery_dod	バッテリーの放電深度を設定します（0～99%）

プロンプト

MCP クライアントが取得してそのまま使用できる、あらかじめ作成されたプロンプトテンプレートです。

プロンプト	引数	説明
status_overview	—	接続、ライブの電力フロー、バッテリー、系統に関する完全なステータスレポート
battery_optimisation	—	バッテリー設定を確認し、DoD／モードの改善を提案します
grid_export_config	—	系統への売電上限を確認し、調整します
operation_mode_change	—	利用可能なモードを説明し、適切なモードへの切り替えを支援します
diagnose_issue	symptom（任意）	完全な診断情報を収集し、問題を特定します
daily_energy_summary	—	今日のエネルギーカウンターを、人が読みやすい表にまとめます

リソース

URI	説明
inverter://status	接続状態とデバイス情報（JSON）
inverter://runtime	すべてのライブセンサー値（JSON）
inverter://settings	すべての設定可能な項目（JSON）
inverter://power/now	リアルタイムの電力フロー — PV、バッテリー、系統、負荷の電力（ワット）を種類ごとに分類
inverter://energy/today	今日のエネルギーカウンター — 発電量、負荷、系統からの購入／系統への売電、バッテリーの充電／放電（kWh）
inverter://battery	バッテリーセンサー、DoD 上限、現在の運転モードをまとめたデータ
inverter://sensors	静的なセンサーカタログ — ライブ値を含まず、すべてのセンサーの ID、名前、単位、種類を表示

インバーターのシリーズ

シリーズ	モデル	備考
ET / EH / BT / BH	ハイブリッド三相	バッテリーに対応。最大 4 系統の PV ストリングに対応
ES / EM / BP	ハイブリッド単相	バッテリーに対応
DT / MS / NS / XS	系統連系のみ	バッテリー非対応

開発

# install runtime + dev dependencies from the lockfile
uv sync

# run the test suite
uv run pytest

# with a coverage report
uv run pytest --cov=goodwe_mcp --cov-report=term-missing

# lint
uv run ruff check src tests

テストはすべてメモリー上の偽インバーターに対して実行されるため、ハードウェアやネットワークへのアクセスは不要です。実際の MCP クライアントセッションと ASGI アプリを通じてサーバーを動作させ、ツール入力の検証、リソースのペイロード、Bearer 認証、DNS リバインディング対策、CLI をテストします。GitHub Actions は Python 3.10 から 3.13 までのバージョンでテストスイートを実行し、プッシュとプルリクエストのたびにコンテナーイメージをビルドします。

ライセンス

リポジトリのルートにある LICENSE ファイルを参照してください。

免責事項

このソフトウェアは GoodWe Inc. とは提携しておらず、同社による承認も受けていません。自己責任でご使用ください。 このソフトウェアは、私が余暇に保守している個人プロジェクトです。 詳細についてはライセンスを参照してください。