Enphase Solar MCPサーバー

Claude Desktopを公式のEnphase Developer API v4に接続するMCPサーバーです。デフォルトでは読み取り専用ですが、オプトインフラグを有効にすることでバッテリーやEV充電器への書き込みも可能です。パスワードのスクレイピングは行わず、OAuth 2.0を使用して自身のシステムデータに安全にアクセスします。

提供機能

30個の読み取りツール（常時有効）（目的別にグループ化）:

グループ	ツール
概要	`get_systems`, `get_system_summary`, `get_latest_telemetry`, `get_live_data`, `get_devices`
累計値	`get_lifetime_production`, `get_lifetime_consumption`, `get_lifetime_battery`, `get_lifetime_grid_import`, `get_lifetime_grid_export`
テレメトリ（間隔）	`get_production_telemetry`, `get_consumption_telemetry`, `get_battery_telemetry`, `get_grid_import_telemetry`, `get_grid_export_telemetry`
イベント / ヘルス	`get_events`, `get_open_events`, `get_alarms`, `get_open_alarms`, `get_event_types`
読み取り専用設定	`get_battery_settings`, `get_storm_guard_settings`, `get_grid_status`, `get_load_control_settings`
EV充電器	`get_ev_charger_devices`, `get_ev_charger_events`, `get_ev_charger_lifetime`, `get_ev_charger_telemetry`, `get_ev_charger_sessions`, `get_ev_charger_schedules`

3個の書き込みツール（ENPHASE_ENABLE_WRITES=1でオプトイン）:

ツール	変更内容
`update_battery_settings`	バッテリーのモード/予備電力/スケジュールを変更
`start_ev_charging`	Enphase IQ EV充電器を開始
`stop_ev_charging`	Enphase IQ EV充電器を停止

これらは物理的な機器の動作を変更し、元に戻すことはできません。LLMによるハードウェア制御を明示的に希望する場合以外は、オフのままにしてください。

プランとハードウェアの注意点

サブスクリプションプラン: 無料の Watt プランでシステム詳細とサイトレベルの発電量/消費電力量をカバーしており、ほとんどの読み取りツールを使用可能です。デバイスごとのテレメトリ、ストームガード、一部のバッテリーエンドポイントには Kilowatt 以上のプランが必要になる場合があります。特定のツールで401エラーが発生する場合は、プランのアップグレードが必要です。
必要なハードウェア: バッテリーツールには Enphase IQ Battery / Encharge が必要です。EV充電器ツールには Enphase IQ EV充電器が必要です（Tesla Wall Connectorやサードパーティ製充電器はEnphaseからは認識されません）。これらで404エラーが発生する場合は、そのデバイスを所有していないことを意味します。
APIエラーはそのまま伝播されるため、どのケースに該当しているかを確認できます。

前提条件

Python 3.11以上
システムが登録されたEnphase Enlightenアカウント
https://developer-v4.enphase.com でのEnphase開発者アカウント（無料のWattプランで十分です — 月間1,000コールまで）

セットアップ

1. 開発者アプリの登録

https://developer-v4.enphase.com にサインアップ
Watt プラン（無料）に登録
新しいアプリケーションを作成
Redirect URI を https://api.enphaseenergy.com/oauth/redirect_uri （デフォルト）に設定
API Key、Client ID、Client Secret を控える

2. システムIDの確認

https://enlighten.enphaseenergy.com にログインし、URLからシステムIDを確認します: https://enlighten.enphaseenergy.com/web/{SYSTEM_ID}/today

（まだ不明な場合は .env で空欄にしておき、サーバー起動後に get_systems を使用して確認してください。）

3. インストール

cd enphase-mcp
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt

4. 認証情報の構成

cp .env.example .env
# Edit .env and fill in API key, client ID, client secret, system ID
# (Optional) uncomment ENPHASE_ENABLE_WRITES=1 to expose write tools.

5. 一回限りの認証フローの実行

python auth_setup.py

スクリプトが認証URLを表示します。同じブラウザでEnlightenにログインした状態でそのURLを開き、自身のシステムへのアクセスを承認してください。認証コードが表示されるページにリダイレクトされます。そのコードをコピーしてターミナルに貼り付けてください。

これにより、アクセストークンとリフレッシュトークンを含む tokens.json が作成されます。以降、クライアントはAPI呼び出しのたびに自動的にトークンを更新します。

6. Claude Desktopへの接続

claude_desktop_config.json を編集します:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "enphase": {
      "command": "/absolute/path/to/enphase-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/enphase-mcp/server.py"]
    }
  }
}

Claude Desktopを完全に再起動します（macOSではウィンドウを閉じるだけでなく、⌘Qで終了してください）。チャット入力欄にツールアイコンが表示されるはずです。「今日と昨日の発電量の比較は？」 や 「今月の最大発電日はいつ？」 といった質問を試してみてください。

トークン更新の動作

アクセストークンの有効期限は1時間です
リフレッシュトークンは約1週間の非アクティブ状態で期限切れになります。APIを呼び出すたびにタイマーがリセットされます
更新に失敗した場合は、再度 python auth_setup.py を実行してください

オプション: 自動キープアライブ

毎週Enphaseにクエリを送信しない場合は、スケジュールに従って keepalive.py を実行し、リフレッシュトークンを維持できます。これは /systems を1回呼び出し、keepalive.log に記録します。macOSの場合、~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist にLaunchAgentを配置し、venvのPythonと keepalive.py を指定します。StartInterval を 259200（3日）に設定すると、7日間の非アクティブ期間内に約4日の余裕が生まれます。launchctl bootstrap gui/$(id -u) <plist> で読み込んでください。

エンドポイントの追加

Enphase v4 APIの仕様は https://developer-v4.enphase.com/docs に記載されており、完全なSwagger仕様は https://developer-v4.enphase.com/swagger/spec/System_API.json にあります（47のエンドポイントがあります。このサーバーはそのほとんどをラップしていますが、マイクロインバーターごとのテレメトリ、ヒートポンプエンドポイント、マルチシステム検索、および一部の特殊なメーター読み取りエンドポイントは除外しています）。

追加するには、既存のパターンに従って server.py に新しいメソッドを追加してください:

@mcp.tool()
def my_new_tool(some_param: str) -> dict:
    """What this returns."""
    sid = client.require_system_id()
    return client.get(f"/systems/{sid}/some_endpoint", params={"x": some_param})

トラブルシューティング

特定のエンドポイントで401エラー: プランの制限です。ほとんどの読み取りはWattプランで動作しますが、一部はKilowatt以上が必要です。

バッテリー/EV充電器エンドポイントで404エラー: システムにそのハードウェアが搭載されていません。

認証URLで406エラー: ブラウザでEnlightenにログインしていません。先にログインしてから認証URLを再度開いてください。

「No tokens found」: python auth_setup.py を実行してください。

Claudeでツールが表示されない: ~/Library/Logs/Claude/ (macOS) または %APPDATA%\Claude\logs\ (Windows) にあるClaude Desktopのログを確認してください。ほとんどの問題は claude_desktop_config.json 内の絶対パス指定に関連しています。

Enphase Solar MCP Server