elicznik-tauron

CLI y servidor MCP no oficiales para el portal Tauron eLicznik (https://elicznik.tauron-dystrybucja.pl). Obtén el consumo de energía, la generación y las lecturas de contadores desde la línea de comandos, o expón estos datos a agentes de IA mediante el Model Context Protocol.

No está afiliado a Tauron. Usa la misma API web interna que el portal.

Características

• Inicio de sesión mediante POST de formulario de Keycloak (no se necesita navegador); las cookies de sesión se guardan en caché en disco y se renuevan automáticamente.

• CLI (elicznik) para listar contadores, obtener datos de energía y registrar lecturas.

• Servidor MCP (elicznik-mcp, stdio) que expone los mismos datos como herramientas para clientes MCP como OpenCode o Claude.

Datos disponibles:

Related MCP server: Enapter MCP Server

Requisitos

Python 3.10+ y uv.

Configuración

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=5842033_61898031_5842033

Las cookies de sesión se guardan en caché en elicznik_session.json (ignorado por git), de modo que solo tienes que iniciar sesión una vez; el cliente se reautentica automáticamente cuando la sesión caduca.

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

Métricas: consumption, generation, net_consumption, net_generation.

Servidor MCP

El servidor expone cuatro herramientas:

• list_meters — lista los putos de medida

• get_energy(metric, start_date, end_date, resolution) — una métrica, con un total sumado y valors por puto

• get_readings(start_date, end_date, resolution) — las cuatro métricas por puto

• get_meter_readings(start_date, end_date, generation) — lecturas acumulativas del registro

OpeCode

Añade a ~/.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

Añade a claude_desktop_config.json:

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

El servidor lee las credenciales del archivo .env del directorio del proyecto (o de las variables de entorno ELICZNIK_USERNAME / ELICZNIK_PASSWORD).

Docker

Se publica una imagen de contenedor en el GitHup Container Registry (ghcr.io/paszymaja/elicznik-tauron). Las credenciales se leen de las variables de entorno ELICZNIK_USERNAME / ELICZNIK_PASSWORD (no se necesita .env); la caché de sesión se escibe en /tmp (efímera).

# 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

Para construr la imagen localmente:

docker build -t elicznik-tauron .

Desarrolo

uv sync --extra mcp
uv run pytest

Notas

• El servidor TLS del portal negocia cifrados que la política OpenSSL predeterinada de Pythón rechaza; el cliente monta un adaptador DEFAULT@SECLEVEL=1 como solución alternativa (consulta session.py).

• Las marcas de tiempo de los CSV horarios indican la hora final; el cliente las normaliza a marcas de tiempo de inicio de hora, de acuerdo con la convención de la API de gráficos.

• Las marcas de tiempo están en hora local (Europe/Warsaw), sin desplazamiento de zona horaria.

Licencia

MIT