energy-mcp

An MCP server for US electricity demand and weather data. It exposes the data as MCP tools, resources, and prompts, runs locally over stdio, and works with any MCP client: Claude Desktop, Claude Code, LangChain's MCP adapters, or the MCP Inspector.

The data ships as a small SQLite file of real observations, so you can clone the repo and run it without a database or an API key.

Python 3.11+ · MCP SDK 1.x (FastMCP) · MIT

What is MCP

MCP is an open protocol from Anthropic. It gives an AI client one standard way to call external tools and read external data, instead of a custom integration per app. A server advertises what it offers, and a client connects and uses it. Servers can offer three things:

• Tools: functions the model can call.
• Resources: read-only content the client loads as context.
• Prompts: reusable templates a user can pick.

This server provides all three.

Tools, resources, and prompts

Tools:

• list_regions(): regions available, with row counts and date coverage.
• query_demand(region, start, end, limit=168): hourly demand in MWh for a date range.
• daily_demand(region, start, end): daily average, peak, and minimum.
• peak_demand(region, start, end): the single highest-demand hour.
• compare_regions(start, end, regions=None): average and peak across regions.
• demand_vs_weather(region, start, end): daily demand joined to that region's temperature.

Resources:

• schema://energy: a plain description of the tables.
• docs://coverage: which regions and dates are currently loaded.

Prompts:

• analyze_demand(region): a starter that walks a region through the tools.

Quickstart

You need uv.

git clone https://github.com/visethchapman/energy-mcp
cd energy-mcp
uv run energy-mcp    # starts the server on stdio; it waits for a client

To click around the tools in a UI, use the MCP Inspector:

uv run mcp dev src/energy_mcp/server.py

Connect it to a client

Claude Desktop

Add this to claude_desktop_config.json (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json) and restart Claude Desktop:

{
  "mcpServers": {
    "energy": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/energy-mcp", "run", "energy-mcp"]
    }
  }
}

Claude Code

claude mcp add energy -- uv --directory /absolute/path/to/energy-mcp run energy-mcp

Then ask in plain language, and the client picks the tools:

• "Which US grid had the highest average demand in July 2024?"
• "When did ERCOT peak in 2024, and how hot was Houston that day?"
• "Compare CISO and PJM demand for the first week of January."

Example output

Real results from the bundled data when a client calls a tool:

> peak_demand(region="ERCO", start="2024-01-01", end="2024-12-31")
{ "region": "ERCO", "period": "2024-08-20 23:00:00", "demand_mwh": 85544.0 }

> compare_regions(start="2024-07-01", end="2024-07-31")
[ {"region":"PJM",  "avg_mwh":109674.4, "peak_mwh":153121.0},
  {"region":"ERCO", "avg_mwh": 60200.6, "peak_mwh": 81200.0},
  {"region":"CISO", "avg_mwh": 32008.4, "peak_mwh": 44727.0},
  {"region":"NYIS", "avg_mwh": 21494.1, "peak_mwh": 28990.0} ]

> demand_vs_weather(region="ERCO", start="2024-07-01", end="2024-07-03")
[ {"day":"2024-07-01", "avg_mwh":67736.3, "tmax_c":37.8, "tmin_c":26.7},
  {"day":"2024-07-02", "avg_mwh":68463.9, "tmax_c":36.1, "tmin_c":27.2},
  {"day":"2024-07-03", "avg_mwh":68017.8, "tmax_c":34.4, "tmin_c":26.7} ]

demand_vs_weather is the interesting one. ERCOT demand climbs with Houston temperature in summer (air-conditioning load), and the tool returns both series so a model can point at the link.

Data

Everything is real, trimmed to calendar year 2024 to keep the file around 5 MB.

Table	Source	Rows
demand (hourly, MWh)	EIA Open Data API, 4 balancing authorities: ERCO, CISO, PJM, NYIS	~35k
daily_weather	NOAA GHCN-Daily, one station near each region's main load zone	~1.5k
stations	NOAA station metadata	4
schema_cards	table documentation	3

The SQLite file is committed, so nothing is fetched at runtime. To rebuild it or widen the date range (this needs a free EIA API key):

uv run --extra build python scripts/build_sample_db.py --start 2023-01-01 --end 2024-12-31

Set ENERGY_MCP_DB to point the server at a different SQLite file.

Safety

• Read-only. The database is opened with SQLite mode=ro, so no tool can write.
• Parameterized SQL. Arguments are bound as parameters, not formatted into the query string, so they cannot inject SQL.
• Validated inputs. Region and date arguments are checked before they reach the database, and bad input comes back as a clear error the model can act on.
• No secrets to run. The data is in the repo; the EIA key is only for rebuilding it.

Development

uv run pytest
uv run mcp dev src/energy_mcp/server.py

Layout:

src/energy_mcp/
  server.py                   # FastMCP server: tools, resources, prompts
  db.py                       # read-only SQLite access
  data/energy_sample.sqlite   # bundled real data
scripts/build_sample_db.py    # how the sample was assembled
tests/test_tools.py

The project uses the MCP 1.x SDK (the FastMCP API), which is what the current Claude Desktop docs and the mcp CLI use. The 2.x SDK is a newer redesign.

Related

energy-text2sql is a text-to-SQL agent over the same EIA and NOAA data. Same data, different interface: one answers questions by writing SQL, this one serves the data as MCP tools.

License

MIT