
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.
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.
Installation
In SourceWeft
- Open Ratebook in the dashboard and add it to a workspace.
- 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]
↑ 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:
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).
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
0Version history
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