Skip to main content
Glama
Energy MCP Belgium

Energy MCP Belgium

README.md
# ⚡ Energy MCP Belgium

**Structured Belgian electricity-system data for MCP-compatible AI applications.**

Energy MCP Belgium exposes read-only MCP tools backed by Elia Open Data, so compatible AI applications can retrieve Belgian generation, load, imbalance and price data without implementing Elia-specific APIs and schemas. The host handles natural language; the server provides structured data and deterministic calculations.

```text
MCP Host
   ↓
Energy MCP Belgium
   ↓
Elia Open Data
```

## Quickstart

Requires Python 3.11+. From a downloaded or cloned checkout:

```sh
python -m venv .venv
# Activate the environment: see commands below.
python -m pip install .
energy-mcp-belgium
# Equivalent: python -m energy_mcp_belgium
```

Activate with `.venv\Scripts\Activate.ps1` in PowerShell, or `source .venv/bin/activate` in a POSIX shell. The server uses **stdio**: a bare launch waits for MCP input; it is not an interactive chat prompt. The package is **not published on PyPI**. Install from the checkout or a locally built wheel; no LLM API key is required.

Configure your MCP host to launch the installed command:

```json
{
  "mcpServers": {
    "energy-belgium": {"command": "energy-mcp-belgium", "args": []}
  }
}
```

The configuration envelope depends on the host. Ensure its PATH includes your environment's executable directory; otherwise use your own absolute installed executable path. See [client setup](docs/clients.md) and the [Inspector example](examples/inspector-config.json).

## Tools

| Tool | Purpose |
|---|---|
| `get_solar_generation` | Belgian national measured/upscaled PV power, MW |
| `get_wind_generation` | Total, onshore or offshore measured/upscaled wind power, MW |
| `get_load` | Belgian total load including estimated losses, MW |
| `get_generation_mix` | Control-area generation preserving both official fuel classifications, MW |
| `get_system_imbalance` | Physical instantaneous imbalance, MW: positive surplus / negative shortage |
| `get_imbalance_prices` | Settlement and distinct marginal activation prices, EUR/MWh |
| `calculate_energy` | Fetch solar/wind/load power and integrate observed energy, MWh |
| `check_data_quality` | Fetch one series and diagnose coverage, gaps, nulls and grid integrity |

**Physical imbalance is not an imbalance price.** Specify MW for `get_system_imbalance`, or EUR/MWh for `get_imbalance_prices`. Hosts should clarify a bare “imbalance” request. Instantaneous system imbalance is not integrated as energy.

## Example

A host can translate “Get Belgian solar generation on 17 November 2026, 10:00–11:00 UTC” into:

```json
{
  "name": "get_solar_generation",
  "arguments": {"start": "2026-11-17T10:00:00Z", "end": "2026-11-17T11:00:00Z"}
}
```

Abbreviated structured response; the first record is shown:

```json
{
  "metadata": {"source": "elia", "dataset_id": "ods209", "unit": "MW", "timezone": "UTC", "resolution_minutes": 15, "record_count": 4},
  "records": [{"timestamp": "2026-11-17T10:00:00Z", "values": {"generation_mw": 293.89}, "dimensions": {"region": "Belgium", "gridconnectiontype": "Total"}, "quality_status": null}]
}
```

The [four-record example](docs/examples/solar-response.json) was retrieved from Elia on 19 November 2026 and may be revised. Complete responses also contain source URL, retrieval time, query bounds, null counts, status and caveats. See the [tool reference](docs/tools.md).

Other requests for a compatible host:

- Get Belgian solar generation between 10:00 and 12:00 UTC on 17 November 2026.
- How much solar **energy** was produced between 12:00 and 13:00 UTC on that date?
- What was the Belgian system imbalance **in MW** during that hour?
- What was the Belgian imbalance **price** during that hour?
- Compare Belgian solar and total wind generation over that period.
- Is the Belgian total-load series complete for that period?

## Tested with real Belgian energy data 🇧🇪

Validated through the official MCP Inspector and bounded live Elia Open Data calls: **8 MCP tools · 6 Elia datasets · read-only access · deterministic analytics**. One real MCP-host configuration was also exercised; model selection remains host-dependent. No certification or endorsement is implied.

[See validation methodology →](docs/validation.md) · [Run the public demo](docs/demo.md) · [Recording guide](docs/recording.md)

## Time and calculations

Use ISO 8601 with `Z` or an explicit UTC offset, UTC quarter-hour aligned boundaries, **inclusive start / exclusive end**, and **at most 24 elapsed hours** per request. Bounds protect provider infrastructure and client context; nothing is silently truncated. Naive timestamps and numeric Unix timestamps are rejected.

Belgian local days may contain **92, 96 or 100 quarter-hours**. Calculations use UTC elapsed time. Split a 25-hour autumn day into requests of at most 24 hours. See [time semantics](docs/time-semantics.md).

`calculate_energy` fetches its own solar/wind/load source and computes MW × interval hours → MWh in Python. Missing intervals are not filled; coverage accompanies observed energy. Duplicate or irregular timestamps are rejected where integration would be ambiguous. `check_data_quality` reports expected/received intervals, missing intervals, nulls, duplicate timestamps, off-grid records, coverage and status. Availability is separate from physical plausibility and provider validation. See [analytics](docs/analytics.md).

## Limitations

- Only Elia is supported, through local stdio MCP. No forecasts, weather, market actions or SolarCast integration are implemented.
- Solar uses ods209 from **26 October 2026**; legacy solar stitching is not implemented.
- Historical records can lag, contain nulls or be revised. Separate calls do not share an immutable snapshot.
- Detailed results can be large: a measured 24-hour generation-mix response contained 1,152 records and approximately **534 KB** of MCP result. Prefer one-hour windows for mix and minute imbalance, or analytics when only totals/coverage are needed.
- Measured client compatibility covers **Inspector CLI 2.16.0** (Node 22.23.4) and **Codex CLI 0.147.0**. Model-driven selection is host-dependent; these are validation examples, not guaranteed behavior for every host/model. No Inspector GUI or remote HTTP deployment is claimed.

## Why this exists

Belgian electricity data is published through provider-specific datasets, fields, units and time conventions. Energy MCP Belgium provides a standard tool interface so compatible applications do not need to reimplement those details. Numerical integration belongs in deterministic code rather than model arithmetic.

## Documentation and contributing

- [Getting started](docs/getting-started.md), [client setup](docs/clients.md), [tool reference](docs/tools.md)
- [Elia contracts](docs/elia-data.md), [time semantics](docs/time-semantics.md), [analytics](docs/analytics.md)
- [Architecture](docs/architecture.md), [sources](docs/research.md), [validation examples](docs/validation.md)
- [Contributing](CONTRIBUTING.md), [security](SECURITY.md), [third-party notices](THIRD_PARTY.md)

Software is **MIT licensed**. Elia data retains its own [Elia Open Data Licence](https://opendata.elia.be/pages/licence/); the software license does not cover that data. Contains information from Elia Transmission Belgium SA, normalized with attribution and provenance. No production or security certification is claimed.

## Related project

[SolarCast Belgium](https://github.com/Junaid-Bashir/solarcast-belgium) focuses on energy forecasting and model benchmarking. Energy MCP Belgium focuses on structured access to Belgian electricity-system data for MCP-compatible applications. There is no dependency or implemented integration between them.