euenergy-mcp

A small Model Context Protocol server that wraps the euenergy.live day-ahead electricity price API as curated, read-only tools for AI agents — hourly prices, the cheapest hours, the current price, and a cross-zone snapshot for ~41 European bidding zones.

Day-ahead market results (sourced from ENTSO-E) are published around midday CEST for the next delivery day and are static thereafter — so the data only changes about once per day. The server caches upstream responses with a long TTL (default 1 hour) keyed by endpoint + params.

Features

• Six read-only tools covering the whole API surface: zones, prices (today/tomorrow), the current hour, cheapest hours, a cross-zone summary, and a historical date range.
• EUR/MWh and EUR/kWh — every price is surfaced as the raw price_eur_mwh (exactly as published) and a price_eur_kwh convenience value (price / 1000).
• Never fakes a zero — a missing or unparseable upstream price/load is surfaced as null with a warnings entry and partial: true, never silently coerced to 0.
• Honest about time — hour timestamps are passed through as UTC, never silently shifted (see the timezone caveat below).
• Long-TTL cache keyed by zone + date, appropriate for once-a-day data.
• Structured errors — every tool returns {"error": …, "error_type": …} instead of throwing across the tool boundary.

Tools

Tool	What it answers
list_zones()	The ≈41 bidding zones: code, ENTSO-E eic, country, label, resolution, currency, lat/lon.
get_prices(zone, day?)	Hourly day-ahead prices for a zone. day = today (default) or tomorrow.
get_current_price(zone)	The price for the current UTC hour (and the next hour).
cheapest_hours(zone, hours?)	The cheapest individual hours today (default 4; upstream clamps to 24) — for load-shifting.
price_summary()	Cross-zone snapshot: per-zone average price, average load (MW), and day-over-day change.
price_history(zone, date_from, date_to)	Hourly prices over a date range (YYYY-MM-DD); pass equal dates for a single past day.

All prices are EUR/MWh on the wire (plus a price_eur_kwh convenience value). All timestamps and day boundaries are UTC. The server is strictly read-only — no write/control endpoints exist.

Prerequisites

• A free euenergy.live API token, minted with your email:

  curl -X POST 'https://euenergy.live/api/v1/[email protected]&label=euenergy-mcp'
  

  The token is returned/emailed; pass it as a Bearer token (the server does this for you). When using this data publicly, attribute "Data via euenergy.live (CC-BY-4.0)".
• Docker (recommended) or Python 3.10+.

Configuration

Configuration is entirely via environment variables:

Variable	Required	Default	Description
EUENERGY_TOKEN	✅	—	Your euenergy.live API token.
EUENERGY_BASE_URL		https://euenergy.live/api/v1	API base URL (override only for testing/proxying).
EUENERGY_TIMEOUT		20	HTTP timeout, seconds.
EUENERGY_CACHE_TTL		3600	Response cache TTL, seconds. Long by design — data changes ~once/day.
MCP_PORT		3000	Port the server listens on.
TZ		UTC	Only affects log readability — prices and timestamps are always UTC.

The token is read lazily: importing the module never requires it; only making a request does. A missing token fails fast with a clear message.

Put the secret in a secret.env file (git-ignored) for Docker Compose:

EUENERGY_TOKEN=your-euenergy-token

Running

Docker Compose (recommended)

docker compose up -d --build

The MCP endpoint is then available at http://localhost:3000/mcp. Override the host port with HOST_PORT:

HOST_PORT=8080 docker compose up -d --build

Docker

docker build -t euenergy-mcp .
docker run --rm -p 3000:3000 --env-file secret.env euenergy-mcp

Local (Python)

pip install -r requirements.txt
export EUENERGY_TOKEN=your-euenergy-token
python server.py

Connecting an MCP client

The server speaks streamable HTTP. Point any MCP client at the /mcp endpoint:

{
  "mcpServers": {
    "euenergy": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

How it works

MCP client ──HTTP /mcp──> euenergy MCP (FastMCP) ──> euenergy.live API (v1)
                                                     GET /zones
                                                     GET /summary/latest
                                                     GET /prices/{today,tomorrow}
                                                     GET /prices?zone&from&to
                                                     GET /cheapest-hours

Units & timezone caveats

[!IMPORTANT] EUR/MWh → EUR/kWh. Prices are published in EUR/MWh. Each tool returns the raw price_eur_mwh (the source of truth, unrounded) plus a price_eur_kwh convenience value (price / 1000, rounded to 5 decimal places, banker's rounding). To compare against a home electricity bill, use the kWh value.

[!IMPORTANT] Everything is UTC. Hour timestamps look like 2026-06-22T10:00:00.000Z and the API's "day" is a UTC calendar day (00:00Z–23:00Z). The day-ahead market itself clears in CET/CEST, so a zone's local midnight does not line up with hour 0 of the returned day. Timestamps are surfaced exactly as received — never silently converted. If you need local-hour reasoning, convert from the UTC ts yourself using the zone's offset (CET = UTC+1, CEST = UTC+2).

Development

pip install -r requirements.txt pytest
pytest -q                                  # network-free unit tests
EUENERGY_TOKEN=... python live_smoke.py    # paced end-to-end smoke test against the real API

live_smoke.py exercises every tool and underlying endpoint against the live API and exits non-zero if any call fails.

Notes & limitations

• Read-only by design — no writes, no control endpoints.
• cheapest_hours and get_current_price cover today only; use get_prices(zone, "tomorrow") or price_history for other days.
• price_change_pct in price_summary is the fractional change vs the previous published day, as provided by the API (e.g. 0.5 ≈ +50%) — passed through verbatim.
• Data is CC-BY-4.0: attribute "Data via euenergy.live (CC-BY-4.0)" when publishing it.
• Not affiliated with euenergy.live.