Ratebook

io.github.cbetzPublished by GitHub account cbetzv0.1.0Updated Oct 24, 2026

Open MCP server for US electricity tariffs: real rate lookup, bill estimates, and when to charge.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Open MCP server for US electricity tariffs that lets an assistant look up real rates, estimate bills, compare plans and find the cheapest charging window.

What you can do
Look up US electricity tariffs and their rate structure from a local rate corpus, including URDB seed data loaded into DuckDB. Estimate a bill for a given usage amount and billing window using the deterministic rate engine. Compare candidate plans against each other for a household's usage. Find the best charge window, i.e. the cheapest hours to charge, from time-of-use schedules. Tariffs can also be handled as JSON, and the same engine powers a Home Assistant integration.
When to use it
Useful when an assistant needs to answer questions about US residential electricity pricing: what a given kWh will cost, which plan is cheaper, or when to schedule EV or appliance charging. Best suited to early adopters, since the project is pre-release with limited utility coverage.
Requirements
Runs locally as a stdio process from the PyPI package ratebook-mcp (Python 3.12+). No authentication, environment variables or headers are declared. Working with corpus data requires first downloading the URDB bulk CSV and loading it into a local DuckDB file; the engine itself needs no data download.
Before you install
The project is explicitly pre-release: utility coverage is still limited, freshness automation is in progress, and there is no public accuracy scorecard yet, so rates may be stale or incomplete. Bill estimates are only as good as the supplied tariff data and usage figures. Loading corpus data downloads a bulk CSV from URDB and writes a local database file.

Installation

In SourceWeft

  1. Open Ratebook in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Ratebook

The open rate engine for the electrified home — an openly licensed database of US electricity tariffs, an open-source rate-calculation engine, and an MCP server, so any app, device, or agent can answer "what will this kWh cost me, and when should I charge?"

[License: Apache-2.0] [Data: CC0-1.0] [Python 3.12+] [CI]

[Ratebook demo — estimate a monthly bill, and see how charging an EV off-peak is ~23% cheaper, computed live by the engine]

↑ The real engine running in the browser. Try it yourself: demo/demo.html.

Status: pre-release. What works today: a deterministic rate engine (Python + a TypeScript port held to it byte-for-byte), cross-validated against NREL's PySAM and shown to reproduce a real bill's total once its components are supplied; an LLM pipeline that extracts tariff structure from utility PDFs; an MCP server; and a Home Assistant integration. What's still in progress: broad utility coverage, freshness automation, and a reproducible public accuracy scorecard. See docs/ROADMAP.md.

Quickstart

The engine has no I/O and no required data download — price a tariff in a few lines:

sh
git clone https://github.com/cbetz/ratebook && cd ratebookuv syncuv run python quickstart.py   # or paste the snippet below into `uv run python`
python
from datetime import datefrom decimal import Decimalfrom ratebook import (    Tariff, TariffIdentity, Sector, EnergyRateStructure, EnergyPeriod, EnergyTier,    Schedule, FixedCharge, FixedChargeUnit, Usage, BillingWindow, estimate_bill,)
# A flat residential tariff: $0.10276/kWh + $11.30/month (PECO Rate R distribution).no_tou = tuple(tuple(0 for _ in range(24)) for _ in range(12))  # 12 months × 24 hours, one periodtariff = Tariff(    energy=EnergyRateStructure(periods=(EnergyPeriod(tiers=(EnergyTier(rate=Decimal("0.10276")),)),)),    schedule=Schedule(weekday=no_tou, weekend=no_tou),    identity=TariffIdentity(plan_code="R", plan_name="Example flat residential", sector=Sector.RESIDENTIAL),    fixed_charges=(FixedCharge(Decimal("11.30"), FixedChargeUnit.PER_MONTH),),)
bill = estimate_bill(tariff, Usage.aggregate(1244), BillingWindow(date(2026, 4, 28), 30))print(f"ok={bill.ok}  total=${bill.total}")   # ok=True  total=$139.13344  →  1244 kWh × $0.10276 + $11.30

Real tariffs round-trip through JSON via Tariff.from_json(...). To work with corpus data, load the URDB seed set (uv run ratebook-data urdb) or run the MCP server (uv run ratebook-mcp) and ask an agent lookup_tariff / estimate_bill / compare_plans / best_charge_window.

Development

Python 3.12+, uv workspace with these packages: packages/ratebook (rate engine), packages/ratebook-data (data plant), packages/ratebook-mcp (MCP server), packages/ratebook-ts (the TypeScript engine port — pnpm + vitest, held to the Python engine via shared JSON test vectors), and packages/ratebook-homeassistant (a Home Assistant custom integration: electricity-price + cheapest-charge-window sensors).

sh
uv sync                            # install all workspace packages + dev toolsuv run pytest                      # Python testsuv run ruff check .                # lintuv run ratebook-data urdb          # download URDB bulk CSV → data/raw/, load into data/ratebook.duckdbuv run ratebook-mcp                # run the MCP server (stdio)
pnpm -C packages/ratebook-ts install && pnpm -C packages/ratebook-ts test   # TS engine + vectors

The PySAM cross-validation runs in CI against committed tariff fixtures (uv sync --group validation installs the oracle). The MCP tool tests additionally need the built corpus and run locally (uv run ratebook-data urdb); they skip otherwise. The two engines must never diverge: both reproduce packages/ratebook/tests/vectors/v0_bills.json byte-for-byte. Regenerate it with uv run python packages/ratebook/tests/generate_vectors.py.

See CONTRIBUTING.md — the highest-value contribution is a tariff correction (report a wrong or stale rate with its source PDF).

License

Code is licensed under Apache-2.0. Published datasets are dedicated to the public domain under CC0-1.0. The seed corpus derives from the U.S. Utility Rate Database (CC0).

Source: README.md at commit d6acd29

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts