wattclear MCP server

US residential electricity tariffs inside Claude, ChatGPT, Cursor and VS Code. Ask what a home will pay a year and which plan is cheapest; the answer comes from published tariffs, priced by wattclear's rate engine.

Endpoint: https://mcp.wattclear.com/mcp (Streamable HTTP, no sign-in)

Add it in 30 seconds

• claude.ai: Settings → Connectors → Add custom connector → paste the endpoint.

• Claude Code:

  claude mcp add --transport http wattclear https://mcp.wattclear.com/mcp

• Cursor (.cursor/mcp.json):

  { "mcpServers": { "wattclear": { "url": "https://mcp.wattclear.com/mcp" } } }

• VS Code (.vscode/mcp.json):

  { "servers": { "wattclear": { "type": "http", "url": "https://mcp.wattclear.com/mcp" } } }

• ChatGPT: turn on Developer mode (Settings → Security and login), then add a developer-mode app with the endpoint and "No authentication".

Then ask, for example:

I use 900 kWh a month in Atlanta, ZIP 30303. What will I pay per year, and which plan is cheapest?

The tools find Georgia Power from the ZIP code, compare its plans for that usage and return the cheapest plan open to every household, its annual cost and the difference to the others.

Related MCP server: US ISO Grid MCP

Tools

Usage is one figure for every month (kwh_per_month) or twelve figures (monthly_kwh). All four tools are read-only and say so in their annotations.

Design

• Four tools, not one per endpoint. Each answer carries the key the next call needs (utility_slug, tariff_label), so a model chains them without guessing.

• Small context cost. The whole tools/list response is about 3.7 KB, roughly 1,000 tokens.

• Short, sourced answers. Every result names its source and licence. Unknown input fails with a message that points to the tool that resolves it.

• Forgiving input. A utility name or a guessed slug that matches one utility resolves, and the answer says what it matched; when several match, they come back as a list to choose from. A plan name works as current_tariff_label the same way. The first eval run caught the need for this: a model guessed georgia-power for georgia-power-co.

• No invented numbers. Prices come from the tariff snapshot and wattclear's rate engine; a plan the published record cannot price is reported as such, not estimated.

How it's built

• TypeScript, the official MCP TypeScript SDK v2 and Cloudflare's Agents SDK (createMcpHandler): a stateless Streamable HTTP server on Cloudflare Workers.

• Workers Rate Limiting at 60 requests a minute per IP address, and Host/Origin allowlists.

• The rate engine and data snapshot come from the wattclear codebase, imported at build time from a sibling folder. This repository holds the MCP layer, its tests and the eval; to try the server, use the public endpoint.

Tests and checks

• 22 unit tests (Vitest) on structure and on agreement between tools. For example, compare_plans' cheapest plan must cost exactly what estimate_annual_cost returns for the same plan and usage.

• MCP Inspector (tools/list, tools/call) against the live endpoint.

• Official MCP conformance scenarios for what the server implements: server-initialize, ping and tools-list pass.

• Eval: eval/run.mjs sends 10 realistic questions through Claude Code with only this server connected, then checks that the model called the right tools and quoted the figures they return. Latest run (4 Oct 2026, Claude Sonnet 5.5): 10/10 passed, right tools 10/10. The first run scored 9/10, and its one miss led to the name matching above. Full table and history: eval/REPORT.md.

Data and licences

• Tariffs: NREL/OpenEI Utility Rate Database, CC0 1.0 (snapshot retrieved 2026-09-29).

• State prices: U.S. Energy Information Administration, residential retail sales, public domain.

• ZIP to utility: NREL, "U.S. Electric Utility Companies and Rates: Look-up by Zip Code (2024)", CC BY 4.0. Attributed in every ZIP answer.

• Estimates exclude taxes unless tax_pct is given. Riders and local fees that a tariff record does not publish are not included.

Need this for your API?

I build tested MCP servers like this one for other companies' APIs: up to 8 tools in 5 business days for a fixed price, with an eval report. See the MCP Server Sprint on Upwork.

Licence

The code in this repository is MIT licensed. The data keeps the licences listed above.