# Unofficial SolarEdge MCP Server

[![CI](https://github.com/holger1411/unofficial-solaredge-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/holger1411/unofficial-solaredge-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](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](https://knowledge-center.solaredge.com/sites/kc/files/se_monitoring_api.pdf).

> **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`** | Current power, live energy flow (PV / battery / grid / load), battery charge level, and today / this-month / lifetime production. Reports both `energy_today_wh` (AC) and `pv_generation_today_wh` (true PV, matches the SolarEdge app). |
| **`solaredge_energy_analysis`** | Production, consumption, self-consumption, feed-in and grid-purchase over a period, plus derived **self-consumption rate** and **self-sufficiency (autarky)**. The summary reports both `ac_production` and `pv_generation` (see below). |
| **`solaredge_diagnosis`** | Inverter status & firmware, data freshness, and (in `comprehensive` mode) battery state of charge and State of Health. |
| **`solaredge_forecast`** | A **heuristic** production estimate from the historical daily average. The SolarEdge API has no forecast endpoint, so this is a simple statistical projection and is clearly labelled as an estimate (no weather data). |

### AC production vs. PV generation (DC-coupled batteries)

Sites with a DC-coupled battery (StorEdge) expose two different "production"
figures, and confusing them is a common source of "the numbers don't match the
app" reports:

- **AC production** (`ac_production`, `energy_today_wh`) — the inverter's AC
  production meter. PV energy that charges the battery over the DC bus never
  crosses this meter, so on sunny days with a charging battery it
  **under-reports** PV.
- **PV generation** (`pv_generation`, `pv_generation_today_wh`) — AC production
  plus the net energy stored in the battery (integrated from `storageData`).
  This matches the value shown in the SolarEdge mobile app / HEMS portal.

Use `pv_generation` for "how much did the system generate?" and `ac_production`
for AC-side energy-balance math (`production = self_consumption + feed_in`).
When `ac_grid_charging` is true the battery was charged from the grid rather
than from PV, so `pv_generation` may be slightly overstated. Adding the battery
correction costs one extra `storageData` API call per analysis (chunked into
≤ 1-week windows for longer ranges, since that is the endpoint's limit).

## Prerequisites

- **Python 3.10+**
- A **SolarEdge Monitoring API key** and your **site ID**:
  - Log in to the [SolarEdge monitoring portal](https://monitoring.solaredge.com).
  - Generate a **site-level** API key under
    *Site Admin → Site Access → Access Control → API Access*.
  - Your **site ID** is the number shown in the portal (also visible in the
    dashboard URL).

> The API allows **300 requests/day** and 3 concurrent calls per token. This
> server caches aggressively and guards the daily budget (see
> [Rate limits](#rate-limits--caching)).

## 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

The server reads its credentials from environment variables. For local use, copy
the example file and fill in your values:

```bash
cp .env.example .env
# then edit .env
```

```dotenv
SOLAREDGE_API_KEY=your_solaredge_api_key_here
SOLAREDGE_SITE_ID=1234567
```

Variables (a local `.env` file or real environment variables both work):

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SOLAREDGE_API_KEY` | yes | – | Your SolarEdge Monitoring API key |
| `SOLAREDGE_SITE_ID` | yes | – | Your SolarEdge site ID (integer) |
| `SOLAREDGE_BASE_URL` | no | `https://monitoringapi.solaredge.com` | API base URL |

## 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_API_KEY": "your_solaredge_api_key_here",
        "SOLAREDGE_SITE_ID": "1234567"
      }
    }
  }
}
```

Passing credentials via `env` (rather than relying on 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_API_KEY": "your_solaredge_api_key_here",
>         "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
```

with `SOLAREDGE_API_KEY` and `SOLAREDGE_SITE_ID` set in the environment
(or `python -m solaredge_mcp.server` with `PYTHONPATH=/path/to/src`, see the
troubleshooting note above).

## Rate limits & caching

- The SolarEdge API permits **300 requests/day** and 3 concurrent requests per
  token.
- Responses are cached by data type: live data ~2 min, time series ~15 min,
  static data (inventory/details) ~1 hour. Cached responses cost no API quota.
- A daily-request counter blocks further calls **before** hitting the API limit,
  returning a clear error instead of an HTTP 429.
- The API key is never written to logs or used in cache keys.

## Known limitations

- **No real forecast.** The SolarEdge API has no forecast endpoint; the forecast
  tool is a historical-average heuristic (no weather).
- **Alerts** are only returned by the API when using an *account-level* key, so
  `diagnosis` does not report alerts when a site-level key is used.
- **Single site (for now).** The server targets one configured site, but the
  internals thread `site_id` everywhere, so multi-site support can be added
  without restructuring.
- Times are interpreted in the **site's local timezone** by the API.

## Development

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

All tests use a mocked HTTP layer and require no real credentials or network
access. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE) © 2026 Holger Koenemann