Enphase Solar MCP Server

An MCP server connecting Claude Desktop to the official Enphase Developer API v4. Read-only by default; battery and EV-charger writes available behind an opt-in flag. No password scraping — clean OAuth 2.0 access to your own system data.

What you get

30 read tools (always on), grouped by purpose:

3 write tools (opt-in via ENPHASE_ENABLE_WRITES=1):

These change physical equipment behavior with no undo. Leave them off unless you specifically want LLM-driven control of your hardware.

Plan and hardware caveats

• Subscription plan. The free Watt plan covers system details + site-level production/consumption — enough for most of the read tools. Per-device telemetry, storm guard, and some battery endpoints may require Kilowatt or higher. A 401 on a specific tool usually means "upgrade your plan."

• Hardware required. Battery tools need an Enphase IQ Battery / Encharge. EV charger tools need an Enphase IQ EV charger (Tesla Wall Connectors and 3rd-party chargers are invisible to Enphase). A 404 from one of these usually means "you don't have that device."

• API errors propagate as-is so you can tell which case you're hitting.

Prerequisites

• Python 3.11+

• An Enphase Enlighten account with your system

• An Enphase Developer account at https://developer-v4.enphase.com (free Watt plan is enough — 1,000 calls/month)

Setup

1. Register a developer app

1. Sign up at https://developer-v4.enphase.com

2. Subscribe to the Watt plan (free)

3. Create a new application

4. Set the Redirect URI to https://api.enphaseenergy.com/oauth/redirect_uri (default)

5. Note your API Key, Client ID, and Client Secret

2. Find your System ID

Log in at https://enlighten.enphaseenergy.com — your system ID is in the URL: https://enlighten.enphaseenergy.com/web/{SYSTEM_ID}/today

(If you don't know it yet, leave it blank in .env and use get_systems once the server is running to discover it.)

3. Install

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

4. Configure credentials

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. Run the one-time auth flow

python auth_setup.py

The script prints an authorization URL. Make sure you're already logged into Enlighten in the same browser, then open the URL, approve access for your own system. You'll be redirected to a page showing your authorization code. Copy it and paste into the terminal.

This creates tokens.json with your access and refresh tokens. From there, the client auto-refreshes on every API call.

6. Connect to Claude Desktop

Edit 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"]
    }
  }
}

Restart Claude Desktop fully (⌘Q on macOS, not just close-window). You should see a tools indicator in the chat input. Ask things like "how much did we produce today vs. yesterday?" or "what was our peak production day this month?".

Token refresh behavior

• Access tokens last 1 hour

• Refresh tokens last ~1 week of inactivity — any API call resets the timer

• If refresh fails, re-run python auth_setup.py

Optional: automated keepalive

If you don't query Enphase weekly, you can run keepalive.py on a schedule to keep the refresh token alive. It calls /systems once and logs to keepalive.log. On macOS, drop a LaunchAgent at ~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist pointing at the venv's Python and keepalive.py, with StartInterval set to 259200 (3 days) — that gives ~4 days of slack inside the 7-day inactivity window. Load it with launchctl bootstrap gui/$(id -u) <plist>.

Adding more endpoints

The Enphase v4 API surface is documented at https://developer-v4.enphase.com/docs and the full Swagger spec is at https://developer-v4.enphase.com/swagger/spec/System_API.json (47 endpoints; this server wraps most of them but skips per-microinverter telemetry, heat-pump endpoints, multi-system search, and a few specialized meter-reading endpoints).

To add one, drop a new method into server.py following the existing pattern:

@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})

Troubleshooting

401 on certain endpoints: Plan-tier issue. Most reads work on Watt; some require Kilowatt+.

404 on battery / EV-charger endpoints: You don't have that hardware on your system.

406 on the auth URL: You're not logged into Enlighten in the browser. Log in first, then re-open the auth URL.

"No tokens found": Run python auth_setup.py.

Claude doesn't see the tools: Check the Claude Desktop logs at ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows). Most issues are absolute-path problems in claude_desktop_config.json.