mcp-server-eia
This server provides MCP tools that enable LLM agents to explore and query the U.S. Energy Information Administration (EIA) Open Data API. You can:
Browse the dataset tree with
eia_browse_routesto discover datasets across 17+ categories (electricity, natural gas, petroleum, coal, renewables, CO₂ emissions, nuclear outages, and energy outlooks like AEO/IEO/STEO) and retrieve metadata such as available frequencies, facets, valid data columns, and date ranges.Identify filterable facets using
eia_list_facets(e.g., state, sector, fuel type) for a given dataset.Get valid facet options with
eia_get_facet_optionsto ensure filters use real values.Query data via
eia_get_datawith column selection, facet-based filtering, frequency selection (annual, monthly, daily, hourly), date range, sorting, and offset pagination (up to 5,000 rows per request).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-eia Show me monthly electricity retail sales for California in 2023"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-server-eia
An MCP server that exposes the U.S. Energy Information Administration (EIA) Open Data API v2 to LLM clients. It provides a small set of generic, composable tools that mirror the API's uniform tree structure (browse → discover facets → query data), giving agents full coverage of all 17 EIA datasets — electricity, natural gas, petroleum, coal, nuclear outages, CO2 emissions, renewables, and the energy outlooks (AEO/IEO/STEO) — without hard-coding hundreds of endpoints.
Tools
Tool | Purpose |
| Explore the dataset tree from any path (empty = the 17 top-level datasets). At a leaf, returns dataset metadata: available frequencies, facet ids, valid data columns, and the covered date range. Primary discovery tool. |
| List the facet ids a dataset can be filtered by (e.g. |
| List the valid option values for a single facet, so filters use real ids. |
| Query dataset rows with column selection, facet filters, frequency, date range, sorting, and pagination. Returns structured JSON with pagination metadata. |
Related MCP server: ipums-mcp
How the EIA API is shaped
The API is a recursive tree. A GET on a route path returns either child
routes (an intermediate node) or leaf metadata (a queryable dataset). The
typical workflow is:
eia_browse_routes(route="")— list top-level datasets.Drill down, e.g.
eia_browse_routes(route="electricity/retail-sales")— read the validdata_columns,frequencies, and facet ids.eia_list_facets/eia_get_facet_options— find valid filter values.eia_get_data(...)— retrieve the numbers.
Conventions
Routes are slash paths without a
v2/prefix, e.g.electricity/retail-sales.Date formats depend on frequency:
2020(annual),2020-01(monthly),2020-01-01(daily),2020-01-01T00(hourly).Facets are passed as
{facet_id: [values]}; sort as[{"column": ..., "direction": "asc"|"desc"}].Pagination:
length(page size, max 5000) andoffset. Reuse thenext_offsetreturned by the previouseia_get_dataresponse.
Requirements
Python
>=3.14uvfor dependency managementA free EIA API key: https://www.eia.gov/opendata/register.php
Setup
uv syncAuthentication
Set the EIA_API_KEY environment variable, or create a .env file in the
project root (loaded automatically at startup; .env is gitignored):
EIA_API_KEY=your_key_hereRunning
uv run python -m eia_mcp.appWith no port env var set, the server runs over stdio (for Claude Desktop, Claude Code, and other local MCP clients).
If
PORTorDATABRICKS_APP_PORTis set, it runs over streamable HTTP on that port, serving MCP at the fixed path/mcpand aGET /healthreadiness endpoint. This is the mode the container image uses.
Container / gateway-hosted deployment
The included Dockerfile builds an image that serves MCP over streamable HTTP
at :8080/mcp (health at /health) — the contract the GSA Obot MCP gateway
expects for a containerized server.
docker build -t mcp-server-eia .
docker run --rm -p 8080:8080 -e EIA_API_KEY=your_key_here mcp-server-eia
curl -s localhost:8080/health # {"status":"healthy","service":"mcp-server-eia"}Publish a public, version-pinned image for the gateway to pull:
./scripts/build-and-push.sh # tags ghcr.io/gsa-tts/mcp-server-eia:<version>The gateway's Docker runtime pulls without registry auth, so the image must be publicly pullable. Set the GHCR package visibility to public after the first push.
Authentication model
This server deals with two distinct credentials on two different hops — do not conflate them:
Credential | Hop | Who supplies / enforces it |
Gateway/transport auth (e.g. Obot API key) | client → gateway → this server | The Obot gateway. In the |
| this server → | Read from the environment at call time ( |
Because the gateway owns transport auth and each user's key is isolated per
instance, the server intentionally sets no FastMCP auth provider — it
assumes zero transport-authentication responsibility.
If this server is ever deployed as a
remoteserver (a public URL reachable independently of the gateway), the MCP endpoint would be unauthenticated. In that case add a FastMCP server-sideJWTVerifiervalidating the gateway/SSO issuer (contingent on that issuer exposing a JWKS endpoint) — notOAuthProxy/OAuthProvider. Keeping the servercontainerized(gateway-guarded) avoids this.
Example MCP client config (stdio)
{
"mcpServers": {
"eia": {
"command": "uv",
"args": ["run", "python", "-m", "eia_mcp.app"],
"cwd": "/path/to/mcp-server-eia",
"env": { "EIA_API_KEY": "your_key_here" }
}
}
}Project layout
src/eia_mcp/
├── app.py # FastMCP init, instructions, transport selection
├── routes.py # HTTP health-check route
├── utils.py # API key, URL building, param encoding, HTTP client, errors
└── tools/
├── __init__.py # register_tools(mcp): wires up all tools
├── browse_routes.py # eia_browse_routes
├── list_facets.py # eia_list_facets
├── get_facet_options.py # eia_get_facet_options
└── get_data.py # eia_get_data
Dockerfile # containerized deployment (:8080/mcp, /health)
scripts/build-and-push.sh # build + push public GHCR image for the gateway
docs/eia-api-swagger/ # EIA API v2 OpenAPI/Swagger referenceEach tool lives in its own file and exposes a register(mcp) function; new tools
are added by dropping a file in tools/ and registering it in
tools/__init__.py.
Data source & attribution
Data is retrieved live from the U.S. Energy Information Administration Open Data API. See the EIA API terms of service for usage and attribution requirements.
Available Tools
4 toolseia_browse_routesBrowse EIA routes / dataset metadataARead-only
Explore the EIA dataset tree, or fetch a leaf dataset's metadata.
Behavior depends on the node type at route:
Intermediate node -> returns
{"type": "routes", "routes": [...]}, each item being a selectable child route id + name/description.Leaf dataset -> returns
{"type": "dataset", ...}with the availablefrequencies,facets(facet ids to filter on), validdatacolumns, and thestartPeriod/endPerioddate coverage. Feed these into eia_get_data.
Start with route="" to discover datasets, then drill down. This is the primary discovery tool; call it before eia_get_data to learn the valid columns, facet ids, and frequency for a dataset.
Inputs: route. Returns: object
eia_get_dataQuery EIA dataset dataARead-only
Query rows from an EIA dataset with filtering, sorting, and paging.
Returns a structured payload: { "route", "frequency", "description", "total": , "offset", "length", "returned": , "has_more": , "next_offset": <int | None>, "data": [ {row}, ... ], "warnings": [ ... ] # present only when relevant }
Workflow: use eia_browse_routes to find the route, its valid
data_columns, frequencies, and facet ids; use eia_get_facet_options
for valid facet values; then call this tool. If data columns are wrong
the API may return empty rows, so verify columns against the metadata.
Inputs: data (required), route (required), end, sort, +5 more. Returns: object
eia_get_facet_optionsGet EIA facet option valuesARead-only
List the valid option values (ids) for one facet of a dataset.
Returns {"route", "facet_id", "total", "options": [...]}. Use the
returned ids as values in the facets argument of eia_get_data, e.g.
facets={"stateid": ["CA", "NY"]}.
Inputs: route (required), facet_id (required). Returns: object
eia_list_facetsList EIA dataset facetsARead-only
List the facet ids you can filter a dataset by.
Returns {"route": ..., "facets": [{"id", "description"}, ...]}. Pass a
facet id to eia_get_facet_options to enumerate its valid values, then use
those values in the facets argument of eia_get_data.
Inputs: route (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear role: browse_routes discovers datasets and metadata, list_facets enumerates facets, get_facet_options lists facet values, and get_data queries rows. There is minor overlap between browse_routes and list_facets since browse_routes already returns facet IDs, but the descriptions clarify when to use each.
All tools follow the consistent eia_<verb>_<noun> pattern with snake_case. The verbs 'browse', 'list', and 'get' are used predictably across the set, making it easy to infer functionality from the name.
With only 4 tools, the server is well-scoped for its purpose. Each tool addresses a distinct step in the EIA data access workflow: discovery, metadata, facet enumeration, and data retrieval, without unnecessary bloat.
The tool set covers the full workflow from discovering routes to fetching filtered data with paging. A minor gap is that there is no direct tool to list data columns or frequencies without calling browse_routes, but that metadata is returned in browse_routes, so it's workable.
Maintenance
Related MCP Connectors
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to operate a US power-grid data pipeline – ingest, plan, run, and monitor datasets like CAISO, ERCOT, and EIA-930 through MCP tools that mirror the CLI.Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that exposes the IPUMS API as LLM tools for browsing metadata, creating and downloading extracts, and generating reproducible R/Python code.23MIT
- FlicenseNot gradedqualityDmaintenanceA FastMCP server that wraps the U.S. Energy Information Administration Open Data API v2, enabling natural-language queries for electricity, petroleum, and other energy statistics via tools like discover_eia_route and get_eia_data.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the U.S. Energy Information Administration's Open Data API, enabling assistants to fetch live energy data via natural language. It provides tools for querying series, browsing data routes, filtering facets, and running custom queries.MIT