Comparador de luz y gas (CNMC)

comparador-luz-gas

CNMC のエネルギー料金プラン比較サイトは、 スペインで唯一の電気・ガス料金の公式比較サービスですが、ウェブフォームに入力しないと 利用できません。その裏側には認証不要のパブリック API があり、一般的な家庭の料金を 調べるだけでも83個のパラメーターが必要です。

これは、わかりやすい API を前面にしたプロキシです。3つの情報を渡すと、価格順に並んだ JSON が返されます。ウェブサイトを経由せず、LLM やスクリプトからの呼び出しを想定しています。

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, ...)

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

さらに、ウェブサイトにはない機能が2つあります。請求書のQRコードを読み取るため、 何も入力する必要がありません。また、各レスポンスで対象外の大手小売事業者を知らせます。 これは、この比較サービスで最も注意が必要な点です。

インストール

PyPI で公開されています。

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

uv を使う場合は uv add comparador-luz-gas を実行します。何もインストールせずに使う場合は、 uvx comparador-luz-gas --cp 28013 --consumo 2600 --texto を実行します。

API

Consulta — 問い合わせ内容

フィールド	デフォルト	説明
codigo_postal	—	必須。例："28013"
consumo_anual_luz	0	kWh/年
consumo_anual_gas	0	kWh/年
potencia	3.45	契約電力（kW）
suministro	"luz"	"luz"、"gas"、または "ambas"
franjas	None	(punta, llano, valle)。指定がない場合は2.0TDプロファイルに基づいて配分されます
vivienda	True	家庭用以外の供給の場合は False
permanencia	2	1 = 契約期間の縛りがないプランのみ
servicios_adicionales	2	1 = 別途契約するサービスがないプランのみ

comparar(consulta, timeout=90) は Resultado を返します。HTTP リクエストは1回だけで、 CNMC の処理時間にあたる3〜8秒で完了します。

Resultado — 返される内容

r.ofertas は安い順に並んでいます。r.to_dict() は、CLI が JSON で出力する内容です。

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

料金には税金の内訳が含まれていません。このレスポンスでは CNMC が内訳を公開していないためです。 契約を切り替える前に、税込み価格かどうかを小売事業者に確認してください。

CLI

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

MCP サーバー

comparador-luz-gas mcp は、追加の依存関係なしで、stdio 経由で比較機能を Claude Desktop や その他の MCP クライアントに提供します。利用できるツールは次のとおりです。

• comparar_ofertas：長期分析を含め、CLI と同じ内容を JSON で返します（料金プラン＋分析）。qr、 または cp と consumo を指定するだけで使えます。max_ofertas（デフォルトは20）でリストを絞り込めます。
• leer_factura_qr：CNMC に問い合わせずに、請求書のQRコードからデータを読み取ります。
• leer_factura_archivo：ディスク上の PDF または画像からQRコードを読み取ります（facturas エクストラが必要です）。

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

leer_factura_archivo の場合は、"args": ["--from", "comparador-luz-gas[facturas]", "comparador-luz-gas", "mcp"] を指定します。 Dockerfile もあります（docker run -i --rm comparador-luz-gas）。MCP の公式レジストリ に io.github.nuncaeslupus/comparador-luz-gas として登録されています。

請求書を読む：テキストではなくQRコード

2021年6月24日のCNMC決議（ BOE-A-2022-16989による改正後）以降、すべての電気料金請求書にはQRコードが付いており、供給内容がすでに内訳表示された状態で比較ツールにアクセスできます：

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...

郵便番号、契約電力、時間帯別の年間消費量、請求対象期間の消費量と日付、料金、金額：まさに比較ツールが求める情報です。形式は電力小売会社ではなくCNMCが定めているため、どの会社にも使えます。会社ごとにパーサーを用意する必要はありません。

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()には依存関係がないため、カメラでQRコードをスキャンするアプリなら、文字列を送信するだけで画像処理の追加機能を完全に省けます。

請求書がスキャン画像の場合は、解像度によります。300 dpiではQRコードの1モジュールがおよそ3 pxとなり、デコーダーの限界ぎりぎりです。400 dpiならJPEG圧縮、回転、ぼけにも耐えます。300 dpiならぼけがない限り問題ありません。200 dpiはきれいな画像の場合のみ、150 dpiでは読み取りできません。数値とその理由については、docs/qr-escaneado.mdをご覧ください。

2つのモード：年間と請求期間

デフォルトでは、CNMCはQRコードの年間消費量を基に12か月分の費用を推定します。--mensual（f.consulta(mensual=True)）を指定すると、実際の日付と消費量を使ってその請求期間にかかった費用を計算するため、請求書に印字された金額と同じ尺度で比較できます：

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

結果を読む際の注意点が2つあります：

• 請求金額には、比較ツールが計上しない項目が含まれます。追加サービス、機器のレンタル、社会的ボーナスなどです。QRコードにはそれらの内訳（impSA、finBS）があるので、比較する前に差し引いてください。
• 2列目は初回特典の割引なしで計算した同じ請求期間の金額であり、2年目の金額ではありません。PVPCでは、適用を外すキャンペーンがないため0になります。

JSONでは、"modo"と"importes"がどちらのモードかを示すので、LLMが1か月分を1年分として読み違えることはありません。

LLMを使わない長期的な評価

interpretar(resultado, anios=3)（CLIのJSONにある"analisis"キー）は、CNMCがすでに返すデータに基づく計算であり、LLMや人がランキングを誤読しないように設計されています。比較ツールはimporte_primer_anioの順に並べるため、ほとんどの場合、一度しか適用されない初回特典のあるプランが首位になります：

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)

各プランのN年間の費用（primer_anio + (N-1) × siguientes）を返し、特に、ランキングで混同されている2つの判断を分けて示します：

• opciones.todas_las_horas_igualとopciones.con_discriminacion_horaria。差額はpreguntaに計算済みで示されます。時間帯別プランは消費時間を変えないとメリットがないため、何かを勧める前にユーザーに確認する必要があります。
• それぞれの中にあるsin_restriccion_de_nuevo_cliente：その電力小売会社の既存顧客も契約できる、最も有利なプランです。

データから導き出せるその他の注意点として、契約期間の縛りと推定違約金、追加サービス、PVPCと最も有利な固定料金プランとの比較もあります。

見落とさないようにしたい点が1つあります。時間帯別プランは、現在のピーク・中間・オフピークの消費配分を使って評価されます。消費時間を変えるとどれくらい得になるか知るには、予想する配分で--franjasを指定して再度問い合わせてください。実際の例では、年間150 kWhをピーク時間帯からオフピーク時間帯に移すと、最も有利な時間帯別プランの料金が660 €から639 €になりました。1年分の洗濯の時間を変更した後でも、最も有利な一律料金プランより8 €安いだけでした。

データが不十分なためできないこともあります。年のどの月に切り替えるのが得かを示すことです。カタログにはプランの提供開始日や終了日はなく、契約可能な顧客の種類しか記載されていません。また、CNMCは比較ツールの過去データを公開していません。2025年9月以降、datos.gob.esでデータの公開申請が提出されていますが、公開データカタログにはそのデータがないとの回答がありました。切り替えのタイミングを決めるのは市場ではなく、契約期間の縛りです。

消費量：対象期間が重要です

QR には直近12か月分が含まれており、1年前の消費量も反映されています。複数の請求書が手元にある場合、anualizar() はより短く、現在の状況に近い期間から年間消費量を推定します。

from comparador_luz_gas import anualizar, desde_fichero

ultimas = [desde_fichero(p) for p in sorted(Path("facturas").glob("*.pdf"))[-6:]]
total, franjas = anualizar(ultimas)

推定金額は変わりますが、ランキングはそれほど変わりません。CNMC が使用するのはお客様の kWh だけで、独自のカタログを適用するため、現在の小売電気事業者による値上げは計算に反映されません。

方法と制限事項

このプロジェクトが返す情報はすべて、CNMC の公式 API（comparador.cnmc.gob.es）から取得しています。独自の価格推定は行わず、CNMC から返された情報に基づいて計算するだけです。これは間違いなく最も透明性の高い情報源ですが、すべてを網羅しているわけではありません。

市場全体を網羅しているわけではありません

CNMC が公開するのは、小売事業者から提出され、技術者が1件ずつ検証したオファーだけです。2026-09-23 に20の郵便番号を対象としてライブ API で確認したところ、次のとおりでした。

• 掲載あり：Naturgy、Repsol、Galp、Octopus、Fenie、Nexus、Lumisa、その他約45社。
• Iberdrola Clientes：オファーは1件のみで、ガスのみ（Plan Gas Hogar RL2 online）。
• Endesa Energía：電気・ガスともにオファーなし。
• TotalEnergies、Plenitude、Holaluz、EDP：オファーなし。

Endesa と Iberdrola は、法律で義務付けられた子会社（Energía XXI、Curenergía）の規制料金である Comercializadora de referencia としてのみ表示されます（PVPC/TUR）。

そのため、各レスポンスには cobertura ブロックが含まれます。「最もお得な料金はどれですか？」という質問への正しい答えは、CNMC が検証した中で最もお得な料金であり、存在する中で最もお得な料金ではありません。

その他の制限事項

• 税金の内訳はありません：金額に IVA の内訳は含まれていません。契約を切り替える前に、小売事業者にご確認ください。
• 履歴データはありません：カタログにはオファーの開始日や有効期限が含まれていないため、何月に切り替えるのがよいかは判断できません（詳しくは長期評価をご覧ください）。
• 時間帯別のオファーは、お客様のピーク／平坦／オフピークの消費割合に基づいて評価されます。この割合は QR または anualizar() から取得します。スペイン本土、バレアレス諸島、カナリア諸島では、2021年6月1日から適用されている Circular 3/2020 の 2.0TD 時間帯を前提としています（ピークは10～14時と18～22時、平坦は平日のそれ以外の時間帯、オフピークは0～8時と祝日）。セウタとメリリャでは時間帯が異なります。以前の時間帯別料金プランを利用していた場合（例：オフピーク時間を自分で選ぶか小売事業者が決めていた「8時間料金」で、規制上の0～8時ではなかった場合）、請求書に記載された過去の消費割合は、現在の時間帯に当てはめた場合の消費量を表しません。そのため、時間帯別オファーの比較にはこの不確実性が引き継がれます。可能であれば、2021年6月1日以降の請求書だけを使ってください。
• 比較ツールは、現在のカタログをお客様の kWh に適用します：現在契約中の小売事業者による値上げは推定に影響しませんが、お客様ご自身の消費量の変化は影響します。

開発

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

HAR キャプチャ（data/har/）と請求書（data/facturas/）は .gitignore に含まれています。これらには CUPS、住所、実際の消費量が記録されています。バージョン管理されているテストでは、架空の QR を使用しています。

claude-arsenal で開発

このリポジトリは、仕様を重視した Claude Code 用プラグインマーケットプレイスであるclaude-arsenalを使って開発されています。まず仕様を作成し、次に失敗するテストを用意して、数値を使った受け入れ基準を定めるという進め方です。含まれているスキルは claude-arsenal/ にあります。