comparador-luz-gas

# comparador-luz-gas

<!-- mcp-name: io.github.nuncaeslupus/comparador-luz-gas -->

<!-- claude-arsenal:attribution: added by claude-arsenal's /init. Delete this block to drop it (it is not put back), or set `attribution = false` in the arsenal config.toml. -->
[![Built with claude-arsenal](https://img.shields.io/badge/built%20with-claude--arsenal-d97756)](https://github.com/nuncaeslupus/claude-arsenal)
<!-- /claude-arsenal:attribution -->

<p align="center">
  <img src="https://raw.githubusercontent.com/nuncaeslupus/comparador-luz-gas/main/docs/hero.png" width="100%" alt="comparador-luz-gas: los 83 parámetros del formulario de la CNMC se quedan en tres datos, código postal, consumo y potencia, o el QR de la factura, y salen las ofertas ordenadas de más barata a más cara, con el aviso de qué comercializadoras grandes faltan">
</p>

El [comparador de ofertas de energía de la CNMC](https://comparador.cnmc.gob.es/) es
la única comparativa oficial de tarifas de luz y gas en España, pero solo se puede
usar rellenando su formulario web. Por debajo hay una API pública sin autenticación
que, para una consulta doméstica normal, pide **83 parámetros**.

Esto es un proxy con una API clara por delante: tres datos entran, JSON ordenado por
precio sale. Pensado para que lo llame un LLM o un script, sin pasar por la web.

```python
from comparador_luz_gas import Consulta, comparar

r = comparar(Consulta(codigo_postal="28013", consumo_anual_luz=2600, potencia=3.45))
r.ofertas[0]  # Oferta(comercializadora='CIDE HCENERGÍA S.A.U', importe_primer_anio=590.19, ...)
```

```bash
comparador-luz-gas --cp 28013 --consumo 2600 --texto
```

Además hace dos cosas que la web no: lee el **QR de la factura** para no tener que
teclear nada, y dice en cada respuesta **qué comercializadoras grandes faltan**, que
es la trampa principal de este comparador.

## Instalación

Está en [PyPI](https://pypi.org/project/comparador-luz-gas/):

```bash
pip install comparador-luz-gas              # solo la consulta
pip install "comparador-luz-gas[facturas]"  # + leer el QR de un PDF o imagen
sudo apt install libzbar0 poppler-utils     # lo que necesita ese extra
```

Con `uv`, `uv add comparador-luz-gas`; o sin instalar nada,
`uvx comparador-luz-gas --cp 28013 --consumo 2600 --texto`.

## La API

### `Consulta` — lo que preguntas

| campo | por defecto | qué es |
|---|---|---|
| `codigo_postal` | — | obligatorio, p. ej. `"28013"` |
| `consumo_anual_luz` | `0` | kWh/año |
| `consumo_anual_gas` | `0` | kWh/año |
| `potencia` | `3.45` | kW contratados |
| `suministro` | `"luz"` | `"luz"`, `"gas"` o `"ambas"` |
| `franjas` | `None` | `(punta, llano, valle)`; si falta, se reparte con el perfil 2.0TD |
| `vivienda` | `True` | `False` si el suministro no es doméstico |
| `permanencia` | `2` | `1` = solo ofertas sin permanencia |
| `servicios_adicionales` | `2` | `1` = solo ofertas sin servicios contratados aparte |

`comparar(consulta, timeout=90)` devuelve un `Resultado`. Es una sola petición HTTP:
tarda entre 3 y 8 segundos, que es lo que tarda la CNMC.

### `Resultado` — lo que devuelve

`r.ofertas` viene ordenado de más barato a más caro. `r.to_dict()` es lo que imprime
el CLI en JSON:

```jsonc
{
  "modo": "anual",
  "importes": "importe_primer_anio / importe_segundo_anio son el coste estimado de 12 meses.",
  "consulta": { "codigo_postal": "28013", "consumo_anual_luz": 2600.0, "reparto_franjas": [745, 639, 1216] },
  "cobertura": {
    "aviso": "El comparador de la CNMC solo incluye ofertas que...",
    "comercializadoras_en_resultado": 28,
    "comercializadoras": ["ADX RENOVABLES, S.L.", "..."],
    "grandes_ausentes": ["ENDESA", "IBERDROLA", "TOTALENERGIES", "..."]
  },
  "ofertas": [
    {
      "comercializadora": "CIDE HCENERGÍA S.A.U",
      "oferta": "Plan Estrella Dúo",
      "importe_primer_anio": 590.19,   // con el descuento de bienvenida
      "importe_segundo_anio": 640.9,   // ya sin él
      "permanencia": false,
      "servicios_adicionales": false,
      "verde": false,
      "validez": "Oferta válida solo para nuevos clientes",
      "precio_unico": true,
      "id_oferta": 7137
    }
  ],
  "alternativa_por_separado": null     // con suministro="ambas": luz + gas sueltos
}
```

Los importes **no llevan desglose de impuestos**: la CNMC no lo publica en esta
respuesta. Antes de cambiarte, confirma con la comercializadora si son con IVA.

### CLI

```bash
comparador-luz-gas --cp 28013 --consumo 2600                      # JSON
comparador-luz-gas --cp 28013 --consumo 2600 --texto --top 5      # tabla legible
comparador-luz-gas --cp 28013 --consumo 2600 --sin-permanencia
comparador-luz-gas --cp 28013 --consumo 2600 --consumo-gas 6000 --suministro ambas
comparador-luz-gas --factura factura.pdf --texto                  # datos del QR
comparador-luz-gas --factura factura.pdf --mensual --texto        # coste de esa factura
comparador-luz-gas --qr 'https://comparador.cnmc.gob.es/comparador/QRE?cp=...'
comparador-luz-gas --factura factura.pdf --solo-datos             # lee el QR y nada más
```

### Servidor MCP

`comparador-luz-gas mcp` sirve el comparador por stdio a Claude Desktop y cualquier
otro cliente MCP, sin dependencias extra. Herramientas:

- `comparar_ofertas`: lo mismo que el CLI en JSON (ofertas + análisis a largo plazo). Basta
  `qr`, o `cp` + `consumo`; `max_ofertas` (20 por defecto) recorta la lista.
- `leer_factura_qr`: los datos del QR de una factura, sin consultar la CNMC.
- `leer_factura`: lee el QR de un PDF o imagen del disco (necesita el extra `facturas`).

```json
{
  "mcpServers": {
    "comparador-luz-gas": { "command": "uvx", "args": ["comparador-luz-gas", "mcp"] }
  }
}
```

Para `leer_factura`: `"args": ["--from", "comparador-luz-gas[facturas]", "comparador-luz-gas", "mcp"]`.
También hay `Dockerfile` (`docker run -i --rm comparador-luz-gas`). Está en el
[registro oficial de MCP](https://registry.modelcontextprotocol.io) como
`io.github.nuncaeslupus/comparador-luz-gas`.

## Leer la factura: el QR, no el texto

Desde la Resolución de la CNMC de 24/06/2021 (modificada por
[BOE-A-2022-16989](https://www.boe.es/diario_boe/txt.php?id=BOE-A-2022-16989)) **toda
factura de electricidad lleva un QR** que apunta al comparador con el suministro ya
desglosado:

```
https://comparador.cnmc.gob.es/comparador/QRE?cp=28013&pP1=4.6&pP2=4.6
   &caP1=740&caP2=660&caP3=757&cups=ES0000000000000000XX&imp=72.50&prE1=0.2288...
```

Código postal, potencias, consumo anual por franja, consumo y fechas del periodo
facturado, precios e importe: justo lo que pide el comparador. Como **el formato lo
fija la CNMC y no la comercializadora**, sirve para cualquier compañía — no hace
falta un parser por marca.

```python
from comparador_luz_gas import comparar, desde_fichero, desde_qr

f = desde_fichero("factura.pdf")  # PDF o imagen: localiza y decodifica el QR (~5 s)
f = desde_qr(texto_del_qr)  # si la app ya lo escaneó: solo urllib.parse
r = comparar(f.consulta())
```

`desde_qr()` no tiene dependencias, así que una app que escanee el QR con la cámara
puede mandar la cadena y saltarse el extra de imagen por completo.

**Si la factura está escaneada**, depende de a cuánto: el QR mide unos 3 px por módulo
a 300 dpi, justo en el límite de los decodificadores. 400 dpi aguanta JPEG, giro y
desenfoque; 300 dpi va bien salvo desenfoque; 200 dpi solo si está limpio; 150 dpi es
imposible. Los números y el porqué, en [docs/qr-escaneado.md](docs/qr-escaneado.md).

### Dos modos: anual y factura

Por defecto la CNMC estima el **coste de doce meses** a partir del consumo anual del
QR. Con `--mensual` (`f.consulta(mensual=True)`) calcula lo que habría costado **ese
periodo de facturación concreto**, con sus fechas y su consumo reales, así que sale
en la misma escala que el importe impreso en la factura:

```
Periodo 2026-07-14→2026-08-16: 146 kWh, pagaste 72.50 €.

  periodo  sin dto.  comercializadora                       oferta
    40.03     51.03  CIDE HCENERGÍA S.A.U                   Plan Estrella Dúo
    47.20     47.20  TRACTAMENT I SELECCIÓ DE RESIDUS, S.A. TARIFA FIJA CLÁSICA - 2.0TD
```

Dos avisos al leerlo:

- El importe de la factura incluye cosas que el comparador no cuenta: servicios
  adicionales, alquiler de equipos, bono social. El QR los desglosa (`impSA`,
  `finBS`); réstalos antes de comparar.
- La segunda columna es el mismo periodo **sin descuento de bienvenida**, no un
  segundo año. En el PVPC sale 0 porque no hay promoción que quitar.

En JSON, `"modo"` e `"importes"` dicen cuál de los dos es, para que un LLM no lea un
mes como si fuera un año.

## Valoración a largo plazo, sin LLM

`interpretar(resultado, anios=3)` (clave `"analisis"` del JSON de la CLI) es aritmética
sobre lo que ya devuelve la CNMC, pensada para que un LLM o una persona no lea mal el
ranking. El comparador ordena por `importe_primer_anio` y ese puesto lo gana casi
siempre una oferta de bienvenida, que **solo se cobra una vez**:

```python
from comparador_luz_gas import comparar, Consulta, interpretar

a = interpretar(comparar(Consulta(codigo_postal="28013", consumo_anual_luz=2200)), anios=3)
print(a["resumen"])
for aviso in a["avisos"]:
    print("-", aviso)
```

Devuelve el coste a N años de cada oferta (`primer_anio + (N-1) × siguientes`) y, sobre
todo, **separa las dos decisiones que el ranking mezcla**:

- `opciones.todas_las_horas_igual` vs `opciones.con_discriminacion_horaria`, con la
  diferencia ya calculada en `pregunta` — es lo que hay que preguntarle al usuario antes
  de recomendarle nada, porque una oferta por tramos solo compensa si va a mover consumo.
- Dentro de cada una, `sin_restriccion_de_nuevo_cliente`: la mejor que también puede
  contratar quien ya es cliente de esa comercializadora.

Más avisos derivados de los datos: permanencia y su penalización estimada, servicios
adicionales, y el PVPC frente a la mejor fija.

Un detalle que conviene no perder de vista: **las ofertas por tramos se valoran con tu
reparto punta/llano/valle actual**. Para saber