Comparador de luz y gas (CNMC)

comparador-luz-gas

CNMC 官方电力和燃气费率比较工具，提供库、CLI 和 MCP 服务。

CNMC 比较工具是西班牙唯一的能源报价官方比较工具，但只能通过网页表单使用；其公开 API 每次查询需要 83 个参数。本项目将其精简为 3 项数据（邮政编码、用量、电力容量）或账单二维码，并以按价格排序的 JSON 格式返回报价，同时提供多年分析，并提示哪些大型零售商未被纳入比较。

快速开始

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

也可以安装：pip install comparador-luz-gas。若要读取 PDF 或图片中的二维码， 运行 pip install "comparador-luz-gas[facturas]" 和 sudo apt install libzbar0 poppler-utils。

示例

实际输出（查询日期：2026-10-20；价格会随市场变化）：

$ 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 €).

不加 --texto 时会输出 JSON，包含键 modo、importes、consulta、cobertura、 ofertas、alternativa_por_separado 和 analisis。每个报价如下：

{"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}

在 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

与 AI Agent 搭配使用

MCP 服务

comparador-luz-gas mcp 通过 stdio 提供比较工具，无需额外依赖。它已列入 MCP 官方注册表，名称为 io.github.nuncaeslupus/comparador-luz-gas。

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

若要读取磁盘中的账单： "args": ["--from", "comparador-luz-gas[facturas]", "comparador-luz-gas", "mcp"]。 也提供 Dockerfile（docker run -i --rm comparador-luz-gas）。

工具	功能
comparar_ofertas	报价 + 长期分析，格式与 CLI 的 JSON 相同。只需提供 qr，或提供 cp + consumo（电力）；燃气则使用 suministro: "gas"，并提供 cp + consumo_gas；两者都比较则使用 suministro: "ambas"，并提供 cp、consumo 和 consumo_gas；max_ofertas（默认值为 20）用于限制列表长度
leer_factura_qr	获取账单二维码中的数据，不查询 CNMC
leer_factura_archivo	读取磁盘上 PDF 或图片中的二维码（需要额外依赖 facturas）

发生错误时会返回 {"ok": false, "error": "ArgumentoInvalido", "message": "..."}。

从 CLI 使用

不使用 MCP 的 Agent 可以调用 CLI：默认会将 JSON 写入 stdout。modo 和 importes 用于说明金额是按年计算，还是按账单周期计算，以免把一个月的金额 误认为一年的金额。参数无效时会以代码 2 退出，并将错误消息写入 stderr。

工作原理

• 向 CNMC 官方 API 发起一次请求（3-8 s，超时限制 90 s）。没有自有价格或缓存：只根据 CNMC 返回的内容进行计算。
• 读取账单二维码。 根据 CNMC 2021 年 6 月 24 日的决议 (BOE-A-2022-16989)，所有 电费账单都带有一个二维码，其中包含邮政编码、功率、按时段划分的年度用量、 账单周期和金额。二维码格式由 CNMC 规定，因此适用于任何 售电公司。desde_qr() 没有依赖项：已扫描二维码的应用只需将字符串传给它。
• 两种模式。 默认计算 12 个月的估算费用。使用 --mensual （f.consulta(mensual=True)）时，计算账单具体周期的费用，可与打印的金额进行比较。
• 长期分析（interpretar()，键 analisis）：计算 N 年费用 （primer_anio + (N-1) × siguientes），因为排名第一的通常是只收取一次的迎新折扣。 区分统一价格与分时价格，指出仅面向新客户的优惠、合约期限及其违约金，并比较 PVPC 与最优惠的固定价格。
• 覆盖范围。 每个响应都会列出已收录的售电公司，以及缺失的大型公司（cobertura.grandes_ausentes）。
• 年化。 anualizar(facturas) 根据多张近期账单推算用量，而不是使用二维码中的滚动 12 个月数据。

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

其他选项：--potencia（kW，默认值为 3,45）、--empresa（非住宅供电）。运行 comparador-luz-gas --help 可查看所有选项。

Consulta 的字段：codigo_postal（必填）、consumo_anual_luz、 consumo_anual_gas、potencia（3.45）、suministro（"luz"、"gas"、"ambas"）、 franjas（(punta, llano, valle)；若未提供，则使用 2.0TD 用量配置）、vivienda（True）、 permanencia 和 servicios_adicionales（2；1 = 仅比较不含附加服务的优惠）。

局限性

• 并非市场普查。 CNMC 只发布售电公司提交并经其验证的优惠信息。截至 2026-09-23，对 20 个邮政编码的核查结果：Endesa、 TotalEnergies、Plenitude、Holaluz 和 EDP 没有优惠；Iberdrola 有一项燃气优惠。 Endesa 和 Iberdrola 仅以 Comercializadora de referencia（PVPC/TUR）的身份出现。结果是 CNMC 已验证的优惠中最好的选择。
• 不含税费明细。 请向售电公司确认金额是否含增值税。
• 账单中包含比价工具未计入的项目：附加服务、设备租赁、社会福利补贴。二维码会列出这些项目（impSA、finBS）；比较前请将其扣除。
• 阶梯优惠按你当前的 punta/llano/valle 用量占比进行估算，采用 Circular 3/2020 规定的 2.0TD 时段（自 2021 年 1 月 6 日起生效；Ceuta 和 Melilla 使用其他时段）。如果打算调整用量，请使用 --franjas 重新计算。如果你当前使用的是更早的分时电价套餐，请只使用该日期之后的账单。
• 没有历史数据。 目录中不包含优惠的生效日期或到期日期，CNMC 也不发布历史数据，因此无法判断哪个月份适合更换套餐。
• 扫描的二维码： 400 dpi 可处理 JPEG、旋转和模糊图像；300 dpi 除模糊图像外均可正常读取；200 dpi 仅适用于清晰图像；150 dpi 无法读取。

文档

• docs/qr-escaneado.md：扫描版账单中的二维码读取方法， 附各分辨率下的识别数据。

开发

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/ 和 data/facturas/ 已加入 .gitignore（包含 CUPS、地址和实际用量）；已纳入版本控制的测试使用虚构的二维码。

相关项目

• claude-arsenal — 由规格引导的 Claude Code 工作流和带有验收关卡的任务队列。
• drawspec — 将声明式图表规格转换为 SVG/PNG/简洁文本，可由大模型编写；包含 MCP 服务。
• doc-control — 让 AI Agent 以受控修订的形式编辑 Word 文档。
• literary-critic — 以专业编辑的方式使用大模型分析手稿。
• integral-job-search — 在 Claude Code 中以求职者为中心的求职搜索。

许可证

MIT