# 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](https://docs.astral.sh/uv/).

```bash
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:

```bash
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:

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

### Claude Code

```bash
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](https://www.eia.gov/opendata/), 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):

```bash
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

```bash
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](https://github.com/visethchapman/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