aiseg2-mcp

aiseg2-mcp

日本語版は README.ja.md をご覧ください。

非公式で読み取り専用の Model Context Protocol サーバーです。Panasonic AiSEG2 ホームエネルギー管理（HEMS）コントローラーに対応しています。MCP クライアント（例：Claude）から、AiSEG2 のローカル Web インターフェースを通じて、ご家庭のリアルタイムな電力の流れ、回路ごとの消費量、回路名、日ごとのエネルギー合計を読み取れます。

このプロジェクトは Panasonic と提携・承認を受けていません。「AiSEG」は Panasonic の商標です。

検証済み環境

以下の環境で開発・テストされています。

• AiSEG2 モデル MKN713 シリーズ
• ファームウェア Ver.2.97I-01

AiSEG2 の Web インターフェースはドキュメント化されておらず、ファームウェアのバージョンによって異なります。別のモデルやファームウェアでは、このサーバーがスクレイピングするページが異なり、一部のツールが動作しない場合があります。 解析エラーが発生した場合は、お使いのモデル／ファームウェアのバージョンを添えて issue を作成してください。

ツール

すべてのツールは読み取り専用（readOnlyHint が注釈され、非破壊で、人が読める title を備えています）です。サーバーは GET と、Web UI 自体が使用する表示専用の更新 POST のみを実行し、設定や /action/ エンドポイントには一切アクセスしません。

すべての結果には as_of（ISO 8601、UTC）が含まれます。これはサーバーが AiSEG2 から値を読み取った時刻、または 2 つの履歴ツールの場合は、それらの元となる SD カードのエクスポートをダウンロードした時刻です。

ツール	タイトル	戻り値
get_power_flow	現在の電力の流れ	発電量／消費量（kW）、買電／売電の状態、バッテリーの状態、発電源、消費量の多い回路
get_circuit_breakdown	回路ごとの現在の電力	測定対象の全回路について、瞬時消費電力（W）を大きい順に表示し、合計も含みます
list_circuits	登録済み回路	登録済みの回路 ID と名前（正式な名称の参照元）
get_daily_totals	今日のエネルギー合計	今日の累積発電量／消費量／買電量／売電量（kWh）
get_history	エネルギー履歴	SD カードのエクスポートから取得した長期エネルギー履歴（Wh）、詳細形式のデータポイント。引数：granularity（30min／hour／day／month／year）、start／end（粒度に応じて YYYY-MM-DD、YYYY-MM、または YYYY）、任意の metrics／circuits フィルター、limit／offset によるページング
get_cost_history	エネルギー料金履歴	SD カードのエクスポートから取得した長期エネルギー料金履歴（JPY）。引数：granularity（day／month／year）、start／end、limit／offset

2 つの履歴ツールを使用するには、AiSEG2 に SD カードを挿入する必要があります — デバイスの SD カード CSV エクスポートを読み取ります。エクスポートは一度ダウンロードされてキャッシュされます（AISEG_CACHE_DIR／AISEG_CACHE_TTL を参照）。そのため、初回の呼び出しは遅く、2 回目以降は速くなります。

インストールと実行

環境に応じて、3 つの実行方法があります。

1. uvx（PyPI — 公開後）

ローカルの（stdio）MCP クライアントに最も簡単な方法です。uv が必要です。

AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uvx aiseg2-mcp

Claude Code に追加します。

claude mcp add aiseg2 \
  --env AISEG_URL=http://192.168.0.216 \
  --env AISEG_PASSWORD=your-digest-password \
  -- uvx aiseg2-mcp

2. docker run（GHCR）

コンテナーはデフォルトで streamable-http トランスポート（長時間稼働するネットワークサービス）を使用します。認証プロキシの背後でのみ公開してください — セキュリティを参照してください。

docker run --rm -p 8000:8000 \
  -e AISEG_URL=http://192.168.0.216 \
  -e AISEG_PASSWORD=your-digest-password \
  ghcr.io/chanyou0311/aiseg2-mcp:latest

3. ソースから実行

Python 3.12 以降と uv が必要です。

uv sync
AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uv run aiseg2-mcp

リモート（認証付き claude.ai Custom Connector）

AiSEG2 を LAN 内に置いたまま claude.ai からサーバーに接続する方法については、examples/remote/ をご覧ください — Docker Compose スタック（MCP + GitHub-OAuth プロキシ + Cloudflare Tunnel）です。

イメージの実行

このリポジトリの役割は、イメージを GHCR にプッシュするところまでです。実際にどこでどのように実行するか（Kubernetes マニフェストなど）は別の場所で定義されています。メンテナー自身のデプロイでは、fumo-infraで定義しています。以下の表は、別のシステムがこのイメージを実行する際に準拠する仕様です。

イメージとタグ	mainへのプッシュごとにghcr.io/chanyou0311/aiseg2-mcp:sha-<7hex>を公開します（作成日時はビルド時刻ではなく、ソースコミットの時刻です）。vX.Y.Zリリースタグでは、追加でX.Y.Z、X.Y、latestも公開します
リッスンポート	8000/tcp — /mcpのストリーミング可能な HTTP MCP エンドポイント
ヘルスチェック	ライブネス：GET /health、レディネス：ポート8000への TCP 接続
必須の環境変数	AISEG_URL、AISEG_PASSWORD（シークレット）
任意の環境変数（デフォルト）	AISEG_USER（aiseg）、AISEG_TRANSPORT（streamable-http — イメージレベルのENVとして設定。uvx経由で実行する場合など、パッケージ自体のデフォルトはstdioです）、AISEG_HOST（0.0.0.0）、AISEG_PORT（8000）、AISEG_DISABLE_DNS_REBINDING_PROTECTION（false）、AISEG_CACHE_DIR（<tempdir>/aiseg2-mcp-cache）、AISEG_CACHE_TTL（3600）、LOG_LEVEL（info） — 詳細は以下の設定を参照してください

このリポジトリにはデプロイ定義（Kubernetes マニフェスト）はありません。

設定（環境変数）

変数	必須	デフォルト	説明
AISEG_URL	はい	—	AiSEG2 のベース URL。例：http://192.168.0.216（http のみ）
AISEG_PASSWORD	はい	—	AiSEG2 ウェブ UI の HTTP Digest パスワード
AISEG_USER	いいえ	aiseg	HTTP Digest ユーザー
AISEG_TRANSPORT	いいえ	stdio	stdioまたはstreamable-http
AISEG_HOST	いいえ	0.0.0.0	バインドするホスト（streamable-http のみ）
AISEG_PORT	いいえ	8000	バインドするポート（streamable-http のみ）
AISEG_DISABLE_DNS_REBINDING_PROTECTION	いいえ	false	Host 許可リストを無効にします（デフォルトではlocalhost／127.0.0.1／[::1]の Host ヘッダーのみ受け付けます） — 信頼できる認証プロキシの背後でのみ使用してください
AISEG_CACHE_DIR	いいえ	<tempdir>/aiseg2-mcp-cache	SD カードの履歴エクスポートをキャッシュする場所
AISEG_CACHE_TTL	いいえ	3600	履歴エクスポートを再ダウンロードするまでキャッシュを再利用する秒数
LOG_LEVEL	いいえ	info	ログレベル

セキュリティ

• 設計上、LAN 内のみでの利用を想定しています。 AiSEG2 は Digest 認証を使用した平文 HTTP で通信するため、AiSEG2 とこのサーバーは信頼できるローカルネットワーク内に置いてください。パスワードは環境変数から読み込まれ、ログに記録されることはありません。
• 読み取り専用です。 デバイスの設定を変更するツールはありません。ツールの提供範囲は、テスト（登録済みツールの許可リスト、ツール名ガード、/action/のソーススキャン、読み取り専用アノテーションのチェック）によって強制されています。
• 認証なしで、信頼できないネットワークにstreamable-httpトランスポートを公開しないでください。 このサーバー自体には認証機能がありません。ネットワークサービスとして実行する場合は、認証を行うリバースプロキシを前段に配置してください。AISEG_DISABLE_DNS_REBINDING_PROTECTION=trueを設定してよいのは、そのプロキシ構成の場合のみです。

謝辞

AiSEG2 のウェブインターフェースは文書化されていません。このプロジェクトは、先行プロジェクトで共有されたリバースエンジニアリングの知見を基にしています。

• shimosyan/aiseg2-influxdb-forwarder — 回路ページングの「最後のページを繰り返す」終了判定と、電力フローのフィールド。
• hiroaki0923/aiseg2-bridge — エンドポイントとページ構成。
• Bugfire/aiseg_download — Digest 認証とデータエンドポイントの規約。

ライセンス

MIT