# Ratebook

> Open database of US electricity tariffs, a deterministic rate engine, and an MCP server — so any app, device, or agent can answer: what will this kWh cost, and when should I charge?

- **Type:** MCP server
- **Install:** `agentstack add mcp-cbetz-ratebook`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cbetz](https://agentstack.voostack.com/s/cbetz)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cbetz](https://github.com/cbetz)
- **Source:** https://github.com/cbetz/ratebook

## Install

```sh
agentstack add mcp-cbetz-ratebook
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)
[](LICENSE-DATA)
[](https://www.python.org/)
[](https://github.com/cbetz/ratebook/actions/workflows/ci.yml)

↑ The real engine running in the browser. Try it yourself: [`demo/demo.html`](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`](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 ratebook
uv sync
uv run python quickstart.py   # or paste the snippet below into `uv run python`
```

```python
from datetime import date
from decimal import Decimal
from 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 period
tariff = 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](https://docs.astral.sh/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 tools
uv run pytest                      # Python tests
uv run ruff check .                # lint
uv run ratebook-data urdb          # download URDB bulk CSV → data/raw/, load into data/ratebook.duckdb
uv 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`](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](LICENSE). Published datasets are dedicated to the public
domain under [CC0-1.0](LICENSE-DATA). The seed corpus derives from the
[U.S. Utility Rate Database](https://apps.openei.org/USURDB/) (CC0).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cbetz](https://github.com/cbetz)
- **Source:** [cbetz/ratebook](https://github.com/cbetz/ratebook)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cbetz-ratebook
- Seller: https://agentstack.voostack.com/s/cbetz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.