mcp-server-eia

Model Context Protocol server for the U.S. EIA Open Data API — domain tools for plants, operations, retail and historical fuel spot prices, AEO projections, and state CO₂ (not raw route mirrors).

Give any AI agent structured access to U.S. energy data from the Energy Information Administration (EIA Open Data API v2).

Scope: stateless live calls to the EIA API only — no database, no hosted projections. Tools return a consistent { "data", "meta" } shape so agents can rely on stable fields.

Prerequisites

• Python 3.11+ (see requires-python in pyproject.toml)
• A free EIA API key (below)
• An MCP client that supports stdio (Cursor, Claude Desktop, etc.)

API key

1. Register: EIA Open Data registration.
2. Recommended: set EIA_API_KEY in the MCP server env (see below). Keys stay out of the repo; each machine uses its own key.
3. Optional: for a terminal, export EIA_API_KEY=... before python -m mcp_server_eia.

Do not commit API keys or paste them into issues/PRs.

Cursor / Claude Desktop / any stdio MCP host

Point the client at this repo’s Python module and pass your key in env:

{
  "mcpServers": {
    "eia": {
      "command": "python3",
      "args": ["-m", "mcp_server_eia"],
      "cwd": "/absolute/path/to/mcp-server-eia",
      "env": {
        "EIA_API_KEY": "paste-your-key-here"
      }
    }
  }
}

• cwd must be the folder where you cloned mcp-server-eia (so imports resolve after pip install -e .).
• Optional: add "EIA_AEO_RELEASE": "2025" to env if you need a different AEO release path than the default.

Where to edit config: Cursor — MCP settings (UI or JSON, depending on version). Claude Desktop — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json (path may vary slightly by version).

Why not call the EIA API directly?

• Fuel types are coded (BIT, NG, …), not “coal” and “gas”.
• Plant inventory is generator-level; useful answers need aggregation to plant.
• AEO data uses table IDs, scenario codes, and region facets that are hard to guess.
• This server wraps those details behind nine domain tools and a stable { "data", "meta" } response shape.

Quick start (install)

git clone https://github.com/abrose1/mcp-server-eia.git
cd mcp-server-eia
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Then add the MCP JSON block above (or export EIA_API_KEY for a one-off terminal run).

Troubleshooting

Issue	What to check
Import / module errors	cwd in MCP config must be the repo root (where pyproject.toml lives). Re-run pip install -e ".[dev]" in that environment.
401 / invalid key	Key typo, or key not passed in env / shell.
Slow calls or 429	EIA rate-limits heavy use; back off and retry. This server retries transient errors; sustained 429s need a pause or fewer parallel tools.

Tools

Tool	Purpose
search_power_plants	EIA-860 inventory aggregated to plants (fuel, state, capacity, status).
get_plant_operations	EIA-923 facility-fuel: generation, fuel use, CF, heat rate.
get_plant_profile	860 + recent 923 in one response.
get_generation_mix	EIA-923 electric-power-operational-data: headline generation mix by fuel (coal, gas, nuclear, hydro, renewables, petroleum, other) for U.S. or a state; annual or one month.
get_capacity_by_fuel	EIA-860 operating-generator-capacity: nameplate MW summed by energy source with plant counts (not plant-level search).
get_electricity_prices	electricity/retail-sales by state/sector.
get_aeo_projections	AEO national fuel prices or regional EMM series (prices, capacity, emissions).
get_fuel_prices	Historical spot/market fuel prices: natural gas (Henry Hub, U.S. citygate/wellhead), coal by basin (coal/market-sales-price), crude WTI/Brent (petroleum/pri/spt). Not the same as AEO category=fuel_prices.
get_steo_forecast	STEO (Short-Term Energy Outlook) 18-month forecasts with historical actuals (monthly or quarterly).
get_state_co2_emissions	SEDS state CO2 (million metric tons) by sector/fuel group.

Example prompts (natural language)

get_fuel_prices returns historical benchmark (spot/market) fuel prices:

Example prompt	What you’ll get
Henry Hub natural gas spot prices for 2024 by month	natural_gas + henry_hub + monthly
Citygate natural gas prices (U.S.) for 2022 monthly	natural_gas + citygate + monthly
U.S. wellhead acquisition price trend, annual from 2018 to 2022	natural_gas + wellhead + annual
Coal open-market price in the Powder River Basin, annual from 2020 through 2023	coal + powder_river + annual
WTI spot crude oil price monthly for 2023	crude_oil + wti + monthly
Brent crude spot price daily in January 2024	crude_oil + brent + daily

get_steo_forecast returns STEO historical actuals + forecast:

Example prompt	What you’ll get
natural_gas_price forecast by month for the next 18 months	natural_gas_price + monthly
crude_oil_price forecast by quarter for the next 18 months	crude_oil_price + quarterly
electricity_demand forecast by month for the next 18 months	electricity_demand + monthly
natural_gas_price forecast by quarter	natural_gas_price + quarterly

STEO series keys: natural_gas_price, crude_oil_price, electricity_demand; frequency is monthly or quarterly.

Plant IDs must be STATE-plantid (e.g. OH-3470), not a bare numeric code.

Development

pytest
ruff check src tests

Live API smoke test (optional)

After pip install -e ., set EIA_API_KEY (same as in MCP env) and run:

export EIA_API_KEY=your-key
python scripts/smoke_eia.py

This hits the real EIA API (tens of seconds), checks two different plants for get_plant_operations, and exercises every tool (including get_generation_mix, get_capacity_by_fuel, and get_fuel_prices). Use before releases or after changing EIA integration code. CI runs unit tests only; smoke needs EIA_API_KEY locally.

Contributing

Issues and PRs welcome. Run pytest, ruff check src tests, and (if you touch EIA calls) python scripts/smoke_eia.py with your key before submitting.

Related

Project Burnout — a separate web dashboard (Burnout / Stranded Assets) that explores US fossil plants using EIA-backed data and its own hosted stack. It is a different product from this MCP server: no shared install, and this repo’s tools are for live EIA API access from MCP clients, not the Burnout app UI.

Releases

See CHANGELOG.md and tags on GitHub.

License

MIT