Ratebook

io.github.cbetz由 GitHub 帳號 cbetz 發布v0.1.0更新於 Oct 24, 2026

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

已驗證STDIO僅桌面金融資料與分析

概覽

AI 產生的概覽

針對美國電價的開放 MCP 伺服器,讓助理查詢真實費率、估算帳單、比較方案並找出最便宜的充電時段。

可以做什麼
從本機費率語料庫查詢美國電價方案及其費率結構,包括載入 DuckDB 的 URDB 種子資料。用確定性費率引擎依指定用電量與帳單期間估算帳單金額。針對家庭用電量比較多個候選方案。依分時電價表找出最佳充電時段,也就是最便宜的小時。方案也能以 JSON 讀寫,同一引擎還驅動一個 Home Assistant 整合。
適用情境
適合助理需要回答美國住宅電價問題時使用,例如某度電要花多少錢、哪個方案較便宜、何時替電動車或家電充電最划算。專案處於預發布階段且涵蓋的電力公司有限,較適合早期使用者。
執行需求
以 stdio 本機程序執行,來自 PyPI 套件 ratebook-mcp,需要 Python 3.12 以上。未宣告任何驗證、環境變數或標頭。使用語料庫資料前須先下載 URDB 批次 CSV 並載入本機 DuckDB 檔案;引擎本身不需下載資料。
安裝前請注意
專案明確處於預發布階段:涵蓋的電力公司仍有限,資料更新自動化尚在開發,也沒有公開的準確度評分,因此費率可能過時或不完整。帳單估算的準確性取決於所提供的方案資料與用電量。載入語料庫會從 URDB 下載批次 CSV 並寫入本機資料庫檔案。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Ratebook,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

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

來源:README.md,提交 d6acd29

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分