Skip to main content
Glama
unofficial-solaredge-mcp

unofficial-solaredge-mcp

by holger1411

Unofficial SolarEdge MCP Server

CI License: MIT Python 3.10+

A lean Model Context Protocol (MCP) server that gives AI assistants like Claude structured access to a SolarEdge PV installation via the official SolarEdge Monitoring API V2 (OAuth 2.0 Site Access).

Version 2.0 is a breaking release. The Monitoring API V1 (API key) was retired on 2026-11-03 and now answers HTTP 410. This server talks to V2 only and authenticates with OAuth 2.0; SOLAREDGE_API_KEY is no longer used.

Disclaimer — this is an unofficial, community project. It is not affiliated with, authorized, maintained, sponsored, or endorsed by SolarEdge Technologies, Inc. "SolarEdge" and related marks are trademarks of their respective owner and are used here only to describe what this software talks to. Use it at your own risk and in accordance with the SolarEdge API Terms & Conditions.

What it does

It exposes four high-level tools that bundle and interpret several API endpoints, so the assistant gets ready-made insights instead of raw payloads:

Tool

What it returns

solaredge_live_status

Latest 15-minute average power flow (PV / load / grid import & export / battery charge & discharge), battery state of energy, today's energy balance and lifetime production.

solaredge_energy_analysis

PV generation, consumption, self-consumption, feed-in, grid purchase and battery flows over a period, plus self-consumption rate and self-sufficiency (autarky).

solaredge_diagnosis

Site status, device inventory (inverters, meters, batteries incl. firmware), inverter output over the last 24 h, data freshness and (in comprehensive mode) battery state of energy.

solaredge_forecast

A heuristic production estimate from the historical daily average (/energy DAY history). The API has no forecast endpoint; no weather data is used and the result is clearly labelled as an estimate.

solaredge_live_status contract

All powers in W, energies in Wh, null when unavailable:

{
  "data_resolution": "QUARTER_HOUR",
  "note": "15-minute averages; the V2 free tier has no live power flow.",
  "timestamp": "2026-11-04T10:45:00+01:00",
  "current_power_w": 3723.6,
  "power_flow": {
    "pv_w": 3723.6, "load_w": 1965.9,
    "grid_import_w": 7.7, "grid_export_w": 3.0,
    "battery_charge_w": 1762.3, "battery_discharge_w": 0.0
  },
  "battery": {"charge_level_pct": 36.7, "status": "charging", "current_power_w": 1762.3},
  "energy_today_wh": 6398.1,
  "pv_generation_today_wh": 6398.1,
  "consumption_today_wh": 30526.5,
  "self_consumption_today_wh": 4515.4,
  "feed_in_today_wh": 45.9,
  "grid_import_today_wh": 18501.4,
  "battery_charged_today_wh": 1836.9,
  "battery_discharged_today_wh": 7509.8,
  "energy_lifetime_wh": 14000500.0
}
  • pv_w / current_power_w = latest non-null /power bucket (PV generation).

  • load_w = the site's consumption meter if present, otherwise derived as pv + grid_import + battery_discharge − grid_export − battery_charge (≥ 0).

  • battery is null for sites without storage; current_power_w is charge − discharge (positive = charging).

  • Today's values come from /overview (site midnight → now). In V2, production.total already contains the energy sent to the battery, i.e. it is the true PV generation — so energy_today_wh and pv_generation_today_wh are equal.

  • energy_lifetime_wh is the sum of /energy YEAR buckets since the installation date (cached 6 h).

Related MCP server: MeteoControl MCP Server

Prerequisites

  • Python 3.10+

  • A SolarEdge site you own or administer, and an OAuth app with Site Access:

    1. Sign in at developer.solaredge.com and create an application of type Site Access.

    2. Scopes: SITE_DATA and DEVICE_DATA.

    3. Redirect URI: http://localhost (or e.g. http://localhost:8765/callback — it must match SOLAREDGE_REDIRECT_URI exactly).

    4. Note the client ID and client secret.

Installation

git clone https://github.com/holger1411/unofficial-solaredge-mcp.git
cd unofficial-solaredge-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Configuration

All settings are SOLAREDGE_-prefixed environment variables (a local .env file is also read; see .env.example):

Variable

Default

Purpose

SOLAREDGE_CLIENT_ID

— (required)

OAuth client ID

SOLAREDGE_CLIENT_SECRET

— (required)

OAuth client secret

SOLAREDGE_SITE_ID

— (required for the tools)

Site ID (printed by solaredge-mcp auth)

SOLAREDGE_REDIRECT_URI

http://localhost

Must match the app's redirect URI

SOLAREDGE_BASE_URL

https://monitoringapi.solaredge.com/v2

API base URL

SOLAREDGE_TOKEN_URL

https://monitoringapi.solaredge.com/v2/oauth2/token

Token endpoint

SOLAREDGE_DAILY_REQUEST_LIMIT

60

Local daily credit budget (see below)

SOLAREDGE_REQUEST_TIMEOUT

30

HTTP timeout in seconds

SOLAREDGE_TOKEN_STORE

keyring

keyring or file

SOLAREDGE_KEYRING_SERVICE

unofficial-solaredge-mcp

Keychain service name

SOLAREDGE_KEYRING_USERNAME

refresh_token

Keychain account name

SOLAREDGE_TOKEN_FILE

~/.config/solaredge-mcp/token.json

File store / fallback

Authorize once: solaredge-mcp auth

export SOLAREDGE_CLIENT_ID=… SOLAREDGE_CLIENT_SECRET=…
.venv/bin/solaredge-mcp auth            # opens the browser
.venv/bin/solaredge-mcp auth --no-browser   # prints the URL instead

The command starts a short-lived local listener on the host/port/path of SOLAREDGE_REDIRECT_URI (default http://localhost → port 80, path /; binding port 80 works unprivileged on macOS — on Linux use e.g. http://localhost:8765/callback and register that URI in the app), opens the SolarEdge consent page (scopes SITE_DATA DEVICE_DATA, 24 months access), validates the state, exchanges the code and stores the refresh token. It prints the granted site_id (set it as SOLAREDGE_SITE_ID) — it never prints tokens. The listener gives up after 10 minutes.

Token storage and rotation

SolarEdge rotates the refresh token on every refresh (the old one becomes invalid immediately) and expires it after 30 days without use. The server keeps the 2-hour access token in memory only, re-reads the stored refresh token before each refresh (another process may have rotated it) and persists the new one immediately. If a refresh fails with invalid_grant, it re-reads the store once and retries; otherwise it asks you to run solaredge-mcp auth again.

  • keyring (default): the bare refresh-token string is stored in the OS keychain. On macOS the server uses the system security tool directly (service → -s, account → -a; the token is passed via stdin, never on the command line) so it can update existing items in place. Elsewhere it uses the keyring package. If no keyring backend is available (e.g. headless Linux), it falls back to the file store.

  • file: JSON file at SOLAREDGE_TOKEN_FILE, written atomically with permissions 0600 (directory 0700).

Reusing an existing keychain item (e.g. an AgenticOS-style secret setup that stores the token as service SOLAREDGE_REFRESH_TOKEN, account agenticos):

SOLAREDGE_KEYRING_SERVICE=SOLAREDGE_REFRESH_TOKEN
SOLAREDGE_KEYRING_USERNAME=agenticos
# equivalent to: security find-generic-password -a agenticos -s SOLAREDGE_REFRESH_TOKEN -w

Upgrading from 1.x

  1. git pull and reinstall: .venv/bin/pip install -e . (adds keyring).

  2. Create a Site Access OAuth app (see Prerequisites).

  3. Replace SOLAREDGE_API_KEY with SOLAREDGE_CLIENT_ID and SOLAREDGE_CLIENT_SECRET in your .env / MCP client config.

  4. Run solaredge-mcp auth once and restart your MCP client.

  5. If you passed meters to solaredge_energy_analysis or relied on alerts, battery State of Health or month-to-date energy, see Known limitations.

Use with Claude Desktop

Add an entry to your claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "solaredge": {
      "command": "/absolute/path/to/unofficial-solaredge-mcp/.venv/bin/solaredge-mcp",
      "env": {
        "SOLAREDGE_CLIENT_ID": "your_client_id",
        "SOLAREDGE_CLIENT_SECRET": "your_client_secret",
        "SOLAREDGE_SITE_ID": "1234567"
      }
    }
  }
}

Run solaredge-mcp auth once beforehand with the same token-store settings (SOLAREDGE_TOKEN_STORE, SOLAREDGE_KEYRING_*, SOLAREDGE_TOKEN_FILE) that the client passes. Passing settings via env (rather than a .env file) is the most reliable approach, because Claude Desktop launches the process from a different working directory.

Troubleshooting: if the server fails to start with No module named 'solaredge_mcp' (editable installs can break on some Python/setuptools combinations), use the interpreter directly and point PYTHONPATH at src:

{
  "mcpServers": {
    "solaredge": {
      "command": "/absolute/path/to/unofficial-solaredge-mcp/.venv/bin/python",
      "args": ["-m", "solaredge_mcp.server"],
      "env": {
        "SOLAREDGE_CLIENT_ID": "your_client_id",
        "SOLAREDGE_CLIENT_SECRET": "your_client_secret",
        "SOLAREDGE_SITE_ID": "1234567",
        "PYTHONPATH": "/absolute/path/to/unofficial-solaredge-mcp/src"
      }
    }
  }
}

Then fully quit and restart Claude Desktop. Try prompts like:

  • "How is my SolarEdge system doing right now?" → solaredge_live_status

  • "Show me my energy balance for the last week." → solaredge_energy_analysis

  • "Run a diagnosis of my system." → solaredge_diagnosis

Use with other MCP clients

The server speaks MCP over stdio. Any MCP-compatible client can launch it via:

/path/to/unofficial-solaredge-mcp/.venv/bin/solaredge-mcp        # same as: solaredge-mcp serve

with SOLAREDGE_CLIENT_ID, SOLAREDGE_CLIENT_SECRET, SOLAREDGE_SITE_ID (and any token-store overrides) set in the environment, or python -m solaredge_mcp.server with PYTHONPATH=/path/to/src.

Credits, rate limits & caching

  • The V2 free tier grants 2,000 credits per month; every API call costs 1 credit. There is also a per-minute limit (~10 calls, x-ratelimit-remaining-minute).

  • A local daily budget (SOLAREDGE_DAILY_REQUEST_LIMIT, default 60/day ≈ 1,800/month) blocks further calls before the quota is exhausted and returns a clear error. Token refreshes do not count.

  • Responses are cached by volatility: live data 15 min (the data resolution is 15 minutes anyway), time series 1 h, static data (site metadata, devices, lifetime energy) 6 h. Cached responses cost nothing.

  • solaredge_live_status costs 4 credits with cold caches (overview, power, meters, storage over the last hour); the first call in a process additionally spends 2 credits on site metadata + lifetime energy (then cached 6 h).

  • Time windows are sent as ISO-8601 UTC instants (2026-11-04T08:57:30Z); responses carry the site's offset.

  • Tokens are never written to logs, URLs, cache keys or error messages.

Known limitations (vs. V1)

  • No live power flow. currentPowerFlow is an Advanced Monitoring feature (Business Pro/Enterprise). The server reports 15-minute averages instead.

  • No battery State of Health and no battery lifetime/capacity details in the free tier; diagnosis says so instead of inventing values (a usable capacity estimate is derived from remaining energy ÷ state of energy).

  • No alerts, no inverter temperature/voltage details from V1's equipment/…/data; diagnosis notes what is not available.

  • The meters parameter of solaredge_energy_analysis was removed; the energy balance comes from /overview.

  • No real forecast. The forecast tool is a historical-average heuristic.

  • Single site. One configured site; internals thread site_id everywhere.

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

All tests use a mocked HTTP layer (incl. the token endpoint) and a fake keyring; they require no real credentials or network access. See CONTRIBUTING.md.

License

MIT © 2026 Holger Koenemann

Available Tools

4 tools
solaredge_diagnosisB

System health: inverter status/firmware, data freshness, and (for check_type='comprehensive') battery state of charge and State of Health. check_type: health|performance|comprehensive.

Inputs: check_type, include_recommendations. Returns: object

solaredge_energy_analysisA

Energy balance and derived metrics (self-consumption rate, self-sufficiency) over a period. time_range: today|1d|1w|1m|3m|1y|custom. For 'custom' supply start_date and end_date as 'YYYY-MM-DD HH:MM:SS'. meters: optional comma list (Production,Consumption,SelfConsumption,FeedIn,Purchased). The summary reports both ac_production (inverter AC meter) and pv_generation (= AC + net battery storage), the latter matching the SolarEdge app/HEMS for DC-coupled batteries.

Inputs: time_range, start_date, end_date, meters. Returns: object

solaredge_forecastA

Heuristic production estimate from the historical daily average (no weather data). forecast_type: daily|weekly.

Inputs: forecast_type, lookback_days. Returns: object

solaredge_live_statusA

Current power, energy flow (PV/battery/grid/load), battery charge level, and today/this-month/lifetime production for the configured site. energy_today_wh is AC production; pv_generation_today_wh adds the energy stored in the DC-coupled battery and matches the SolarEdge app/HEMS.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: diagnosis for system health, energy analysis for historical metrics, forecast for production estimates, and live status for current data. No overlaps or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent 'solaredge_' prefix followed by a descriptive verb_noun pattern (e.g., live_status, energy_analysis). Naming is uniform and predictable.

    Tool Count5/5

    Four tools cover the core aspects of solar monitoring: health, historical analysis, forecast, and live status. The count is appropriate for the domain without being excessive or insufficient.

    Completeness4/5

    The set covers essential monitoring and analysis functions. Minor gaps exist, such as missing tools for site configuration, alerts, or detailed component history, but core workflows are supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to look up solar permitting authorities, estimate solar production via PVWatts, and retrieve irradiance data. It streamlines the creation of solar-aware workflows by integrating industry-standard APIs like NREL.
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      An MCP server that enables natural language interaction with the MeteoControl VCOM API v2 for monitoring solar array installations. It allows users to retrieve real-time and historical energy data, system alerts, and detailed asset configuration metrics.
      4
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server for Intervals.icu integration. Access your training data, wellness metrics, and performance analysis through Claude and other LLMs.
      48
      39
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides comprehensive access to Tigo Energy solar system data and analytics. It enables AI assistants to interact with your Tigo solar monitoring system to retrieve production data, performance metrics, system health information, and maintenance insights.
      MIT