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.

Related MCP server: germany-mcp-server

Tools

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/keys?email=you@example.com&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:

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

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.