unofficial-solaredge-mcp
# Unofficial SolarEdge MCP Server
[](https://github.com/holger1411/unofficial-solaredge-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
A lean [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
gives AI assistants like Claude structured access to a
[SolarEdge](https://www.solaredge.com) 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](https://monitoring.solaredge.com/solaredge-web/p/license).
## 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:
```json
{
"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).
## 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](https://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
```bash
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`](.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`
```bash
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`](https://pypi.org/project/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`):
```bash
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](#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](#known-limitations-vs-v1).
## 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`
```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`:
>
> ```json
> {
> "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:
```bash
/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
```bash
.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](CONTRIBUTING.md).
## License
[MIT](LICENSE) © 2026 Holger Koenemann
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.