elicznik-tauron

Unofficial CLI and MCP server for the Tauron eLicznik portal (https://elicznik.tauron-dystrybucja.pl). Fetch energy consumption, generation and meter readings from the command line or expose them to AI agents via the Model Context Protocol.

Not affiliated with Tauron. Uses the same internal web API the portal uses.

Features

• Login via Keycloak form POST (no browser needed); session cookies cached on disk and auto-refreshed.

• CLI (elicznik) to list meters, fetch energy data and register readings.

• MCP server (elicznik-mcp, stdio) exposing the same data as tools for MCP clients such as OpenCode or Claude.

Available data:

Related MCP server: Enapter MCP Server

Requirements

Python 3.10+ and uv.

Setup

uv sync --extra mcp
cp .env.example .env   # then fill in your credentials

.env:

ELICZNIK_USERNAME=your-login-or-email
ELICZNIK_PASSWORD=your-password
# Optional: pick a specific metering point if you have more than one
# ELICZNIK_SITE=123456_123_123

Session cookies are cached to elicznik_session.json (gitignored) so you only log in once; the client re-authenticates automatically when the session expires.

CLI

# List metering points
uv run elicznik meters

# Hourly consumption for a day (defaults: today, metric=consumption, resolution=hour)
uv run elicznik energy --metric consumption --from 2026-08-24 --to 2026-08-24

# Daily / monthly / yearly totals
uv run elicznik energy --metric consumption --resolution day   --from 2026-08-01 --to 2026-08-26
uv run elicznik energy --metric consumption --resolution month --from 2026-01-01 --to 2026-08-26
uv run elicznik energy --metric generation  --resolution year  --from 2026-01-01 --to 2026-08-26

# Output formats: table (default), csv, json
uv run elicznik energy --metric consumption --resolution day --from 2026-08-01 --to 2026-08-26 --format json

# Cumulative meter register readings (billing readings)
uv run elicznik readings --from 2026-08-01 --to 2026-08-26
uv run elicznik readings --from 2026-08-01 --to 2026-08-26 --generation   # returned energy

Metrics: consumption, generation, net_consumption, net_generation.

MCP server

The server exposes four tools:

• list_meters — list metering points

• get_energy(metric, start_date, end_date, resolution) — one metric, with a summed total and per-point values

• get_readings(start_date, end_date, resolution) — all four metrics per point

• get_meter_readings(start_date, end_date, generation) — cumulative register readings

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "elicznik": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/home/paszymaja/github_projects/elicznik-tauron", "elicznik-mcp"],
      "enabled": true
    }
  }
}

Claude for Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "elicznik": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/elicznik-tauron", "run", "elicznik-mcp"]
    }
  }
}

The server reads credentials from .env in the project directory (or from ELICZNIK_USERNAME / ELICZNIK_PASSWORD environment variables).

Docker

A container image is published to the GitHub Container Registry (ghcr.io/paszymaja/elicznik-tauron). Credentials are read from the ELICZNIK_USERNAME / ELICZNIK_PASSWORD environment variables (no .env needed); the session cache is written to /tmp (ephemeral).

# CLI
docker run --rm \
  -e ELICZNIK_USERNAME -e ELICZNIK_PASSWORD \
  ghcr.io/paszymaja/elicznik-tauron:latest meters

docker run --rm \
  -e ELICZNIK_USERNAME -e ELICZNIK_PASSWORD \
  ghcr.io/paszymaja/elicznik-tauron:latest \
  energy --metric consumption --resolution day --from 2026-08-01 --to 2026-08-26

# MCP server over stdio (note the -i flag for stdin)
docker run -i --rm \
  -e ELICZNIK_USERNAME -e ELICZNIK_PASSWORD \
  ghcr.io/paszymaja/elicznik-tauron:latest mcp

To build the image locally:

docker build -t elicznik-tauron .

Contract check

Tauron's API is undocumented and can change without notice. contract-check probes the parts of the API this project depends on and reports, structurally, whether each still behaves as expected:

uv run elicznik contract-check

It verifies (in order): the Keycloak login flow, the metering-point list, the hourly CSV export, the chart API, the register-readings API, and the normalized readings — and exits non-zero if any check fails.

Privacy: the output contains only check names and pass/fail flags (plus a generic structural reason on failure). It never prints metering-point identifiers, addresses, usernames, or energy values, so it's safe to run in a public CI pipeline.

Scheduled CI

The .github/workflows/contract-check.yml workflow runs contract-check weekly (Monday 08:00 UTC) and on demand (workflow_dispatch), using the ELICZNIK_USERNAME / ELICZNIK_PASSWORD repository secrets. On failure it opens (or comments on) a contract-check GitHub issue so a Tauron API change is surfaced without leaking any data.

Development

uv sync --extra mcp
uv run pytest

Notes

• The portal's TLS server negotiates ciphers that Python's default OpenSSL policy rejects; the client mounts a DEFAULT@SECLEVEL=1 adapter as a workaround (see session.py).

• Hourly CSV timestamps label the ending hour; the client normalizes them to start-of-hour timestamps matching the chart API convention.

• Timestamps are in local time (Europe/Warsaw), without a timezone offset.

License

MIT