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 分