unofficial-solaredge-mcp
Use the MCP server to query and analyze one configured SolarEdge PV site through four tools.
Get latest 15-minute power flow, battery state, and today/lifetime production.
Analyze energy balance over today, 1d, 1w, 1m, 3m, 1y, or custom ranges, including self-consumption and self-sufficiency.
Run system diagnostics for inverter status, firmware, data freshness, and battery state.
Generate heuristic daily or weekly production forecasts from historical daily averages.
Unofficial SolarEdge MCP Server
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_KEYis 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 |
| 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. |
| PV generation, consumption, self-consumption, feed-in, grid purchase and battery flows over a period, plus self-consumption rate and self-sufficiency (autarky). |
| Site status, device inventory (inverters, meters, batteries incl. firmware), inverter output over the last 24 h, data freshness and (in |
| A heuristic production estimate from the historical daily average ( |
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/powerbucket (PV generation).load_w= the site's consumption meter if present, otherwise derived aspv + grid_import + battery_discharge − grid_export − battery_charge(≥ 0).batteryisnullfor sites without storage;current_power_wischarge − discharge(positive = charging).Today's values come from
/overview(site midnight → now). In V2,production.totalalready contains the energy sent to the battery, i.e. it is the true PV generation — soenergy_today_whandpv_generation_today_whare equal.energy_lifetime_whis the sum of/energyYEAR 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:
Sign in at developer.solaredge.com and create an application of type Site Access.
Scopes:
SITE_DATAandDEVICE_DATA.Redirect URI:
http://localhost(or e.g.http://localhost:8765/callback— it must matchSOLAREDGE_REDIRECT_URIexactly).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 |
| — (required) | OAuth client ID |
| — (required) | OAuth client secret |
| — (required for the tools) | Site ID (printed by |
|
| Must match the app's redirect URI |
|
| API base URL |
|
| Token endpoint |
|
| Local daily credit budget (see below) |
|
| HTTP timeout in seconds |
|
|
|
|
| Keychain service name |
|
| Keychain account name |
|
| 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 insteadThe 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 systemsecuritytool 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 thekeyringpackage. If no keyring backend is available (e.g. headless Linux), it falls back to the file store.file: JSON file atSOLAREDGE_TOKEN_FILE, written atomically with permissions0600(directory0700).
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 -wUpgrading from 1.x
git pulland reinstall:.venv/bin/pip install -e .(addskeyring).Create a Site Access OAuth app (see Prerequisites).
Replace
SOLAREDGE_API_KEYwithSOLAREDGE_CLIENT_IDandSOLAREDGE_CLIENT_SECRETin your.env/ MCP client config.Run
solaredge-mcp authonce and restart your MCP client.If you passed
meterstosolaredge_energy_analysisor 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.jsonWindows:
%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 pointPYTHONPATHatsrc:{ "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 servewith 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_statuscosts 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.
currentPowerFlowis 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;
diagnosissays 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;diagnosisnotes what is not available.The
metersparameter ofsolaredge_energy_analysiswas 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_ideverywhere.
Development
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytestAll 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 toolssolaredge_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for the Seline Analytics API
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseCqualityDmaintenanceAn 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.4Apache 2.0
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server for Intervals.icu integration. Access your training data, wellness metrics, and performance analysis through Claude and other LLMs.4839MIT
- AlicenseNot gradedqualityDmaintenanceA 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