Comparador de luz y gas (CNMC)

comparador-luz-gas

El comparador oficial de tarifas de luz y gas de la CNMC, como librería, CLI y servidor MCP.

El comparador de la CNMC es la única comparativa oficial de ofertas de energía en España, pero solo se usa a través de un formulario web; su API pública pide 83 parámetros por consulta. Este proyecto la reduce a tres datos (código postal, consumo, potencia) o al QR de la factura, y devuelve las ofertas en JSON ordenadas por precio, con un análisis a varios años y el aviso de qué comercializadoras grandes no están en el comparador.

Inicio rápido

uvx comparador-luz-gas --cp 28013 --consumo 2600 --texto --top 5

O instalado: pip install comparador-luz-gas. Para leer el QR de un PDF o una imagen, pip install "comparador-luz-gas[facturas]" y sudo apt install libzbar0 poppler-utils.

Ejemplo

Salida real (consulta del 2026-10-20; los precios cambian con el mercado):

$ comparador-luz-gas --cp 28013 --consumo 2600 --texto --top 5
  1er año    2º año  comercializadora                       oferta
----------------------------------------------------------------------------------------------------
   653.02      0.00  Comercializadora de referencia         PVPC Histórico 19/10/2025 - 19/10/2026
   655.15    655.15  ENERGIA NUFRI SL                       ENERGIA NUFRI - CON HORARIOS
   657.85    721.45  niba                                   niba Zen
   661.53    661.53  ENERGIA NUFRI SL                       ENERGIA NUFRI - UNIVERSAL CON HORARIOS
   662.80    713.51  CIDE HCENERGÍA S.A.U                   Plan Estrella Dúo

70 ofertas de 28 comercializadoras.
No están en el comparador: ENDESA, IBERDROLA, TOTALENERGIES, HOLALUZ, EDP, GALP.
[...]

A 3 años, lo más barato es ENERGIA NUFRI SL «ENERGIA NUFRI - CON HORARIOS»: 1965.45 €
(655.15 €/año en régimen). ¿Prefieres pagar lo mismo a cualquier hora o puedes concentrar
el consumo en las horas baratas? Con tu reparto actual gana la discriminación horaria por
41.79 €: [...]
- La mejor a 3 años es solo para nuevos clientes: [...]
- El PVPC sale 2.13 € más barato al año que la mejor fija (653.02 € frente a 655.15 €),
  pero es variable: [...]
- 13 de 70 ofertas tienen permanencia (penalización de 16.87 a 37.42 €).

Sin --texto imprime JSON con las claves modo, importes, consulta, cobertura, ofertas, alternativa_por_separado y analisis. Cada oferta:

{"comercializadora": "Comercializadora de referencia", "oferta": "PVPC Histórico 19/10/2025 - 19/10/2026",
 "importe_primer_anio": 653.02, "importe_segundo_anio": 0.0, "permanencia": false,
 "servicios_adicionales": false, "verde": false, "validez": "Válida para consumidores con derecho a PVPC",
 "precio_unico": false, "id_oferta": 180, "penalizacion_estimada": 0, "solo_nuevos_clientes": false}

Desde Python:

from comparador_luz_gas import Consulta, comparar, desde_fichero, interpretar

r = comparar(Consulta(codigo_postal="28013", consumo_anual_luz=2600, potencia=3.45))
r.ofertas[0]  # la más barata el primer año
r.to_dict()  # lo mismo que imprime el CLI
interpretar(r, anios=3)["resumen"]  # valoración a 3 años

r = comparar(desde_fichero("factura.pdf").consulta())  # todo desde el QR de la factura

Uso con agentes de IA

Servidor MCP

comparador-luz-gas mcp sirve el comparador por stdio, sin dependencias extra. Está en el registro oficial de MCP como io.github.nuncaeslupus/comparador-luz-gas.

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

Para leer facturas del disco: "args": ["--from", "comparador-luz-gas[facturas]", "comparador-luz-gas", "mcp"]. También hay Dockerfile (docker run -i --rm comparador-luz-gas).

Los errores vuelven como {"ok": false, "error": "ArgumentoInvalido", "message": "..."}.

Desde el CLI

Un agente sin MCP puede llamar al CLI: por defecto escribe JSON en stdout. modo e importes dicen si los importes son anuales o de un periodo de factura, para que no se confunda un mes con un año. Un argumento inválido sale con código 2 y el mensaje en stderr.

Cómo funciona

• Una petición a la API oficial de la CNMC (3-8 s, límite 90 s). No hay precios propios ni caché: solo cuentas sobre lo que responde la CNMC.
• Lee el QR de la factura. Desde la Resolución de la CNMC de 24/06/2021 (BOE-A-2022-16989) toda factura de luz lleva un QR con código postal, potencias, consumo anual por franja, periodo e importe. El formato lo fija la CNMC, así que vale para cualquier comercializadora. desde_qr() no tiene dependencias: una app que ya escaneó el QR le pasa la cadena.
• Dos modos. Por defecto, coste estimado de 12 meses. Con --mensual (f.consulta(mensual=True)), el coste del periodo concreto de la factura, comparable con el importe impreso.
• Análisis a largo plazo (interpretar(), clave analisis): coste a N años (primer_anio + (N-1) × siguientes), porque el primer puesto suele ganarlo un descuento de bienvenida que se cobra una vez. Separa precio único frente a discriminación horaria, señala las ofertas solo para nuevos clientes, la permanencia y su penalización, y el PVPC frente a la mejor fija.
• Cobertura. Cada respuesta lista las comercializadoras presentes y las grandes que faltan (cobertura.grandes_ausentes).
• Anualizar. anualizar(facturas) extrapola el consumo de varias facturas recientes en vez de usar los 12 meses rodantes del QR.

CLI

comparador-luz-gas --cp 28013 --consumo 2600                      # JSON
comparador-luz-gas --cp 28013 --consumo 2600 --texto --top 5      # tabla
comparador-luz-gas --cp 28013 --consumo 2600 --sin-permanencia
comparador-luz-gas --cp 28013 --consumo 2600 --consumo-gas 6000 --suministro ambas
comparador-luz-gas --cp 28013 --consumo 2600 --franjas 600,700,1300 --anios 5
comparador-luz-gas --factura factura.pdf --texto                  # compara con los datos del QR
comparador-luz-gas --factura factura.pdf --mensual --texto        # coste de ese periodo
comparador-luz-gas --qr 'https://comparador.cnmc.gob.es/comparador/QRE?cp=...'
comparador-luz-gas --factura factura.pdf --solo-datos             # solo lee el QR

Otras opciones: --potencia (kW, 3,45 por defecto), --empresa (suministro que no es vivienda). comparador-luz-gas --help las lista todas.

Campos de Consulta: codigo_postal (obligatorio), consumo_anual_luz, consumo_anual_gas, potencia (3.45), suministro ("luz", "gas", "ambas"), franjas ((punta, llano, valle); si falta, perfil 2.0TD), vivienda (True), permanencia y servicios_adicionales (2; 1 = solo ofertas sin ellos).

Limitaciones

• No es un censo del mercado. La CNMC solo publica ofertas que las comercializadoras le remiten y valida. Comprobado el 2026-09-23 sobre 20 códigos postales: Endesa, TotalEnergies, Plenitude, Holaluz y EDP no tienen ofertas; Iberdrola, una de gas. Endesa e Iberdrola solo aparecen como Comercializadora de referencia (PVPC/TUR). El resultado es la mejor entre las verificadas por la CNMC.
• Sin desglose de impuestos. Confirma con la comercializadora si el importe lleva IVA.
• 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.
• Las ofertas por tramos se valoran con tu reparto punta/llano/valle actual, con los tramos 2.0TD de la Circular 3/2020 (vigentes desde el 1/06/2021; Ceuta y Melilla usan otros). Si piensas mover consumo, repite con --franjas. Si vienes de una tarifa de discriminación horaria anterior, usa solo facturas posteriores a esa fecha.
• Sin histórico. El catálogo no lleva fechas de alta ni caducidad, y la CNMC no publica el histórico, así que no se puede decir en qué mes conviene cambiar.
• QR escaneado: 400 dpi aguanta JPEG, giro y desenfoque; 300 dpi va bien salvo desenfoque; 200 dpi solo si está limpio; 150 dpi no se lee.

Documentación

• docs/qr-escaneado.md: lectura del QR en facturas escaneadas, con las cifras por resolución.

Desarrollo

make sync && make lint && make test
make test-live       # consulta la API real
make test-facturas   # lee el QR de los PDFs de data/facturas/, si los hay

data/har/ y data/facturas/ están en .gitignore (llevan CUPS, dirección y consumos reales); los tests versionados usan un QR inventado.

Proyectos relacionados

• claude-arsenal — flujo de Claude Code guiado por especificaciones y cola de tareas con puertas de aceptación.
• drawspec — especificación declarativa de diagramas a SVG/PNG/texto limpio, escribible por LLMs; incluye servidor MCP.
• doc-control — permite a agentes de IA editar documentos Word como cambios controlados.
• literary-critic — análisis de manuscritos con LLM al modo de un editor profesional.
• integral-job-search — búsqueda de empleo centrada en el candidato, dentro de Claude Code.

Licencia

MIT