eia-energy-mcp-server

---

Tools

Seven tools covering the two-phase EIA workflow — find the right dataset route, pull the data, and query spilled results via SQL:

Tool	Description
eia_browse_routes	Lists child routes under a given path in the EIA dataset taxonomy. Start at root to see top-level categories, then drill into subcategories and leaf routes.
eia_describe_route	Returns full metadata for a leaf route: available facets with valid values, data column names, frequency options, units, and date range. Call before eia_query_route to understand filter options.
eia_search_routes	Fuzzy text search across route names, descriptions, and category labels. Resolves natural-language queries like "gasoline retail prices" or "solar capacity by state" to matching route paths.
eia_query_route	Fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. Spills large result sets to a DataCanvas table for SQL analysis.
eia_dataframe_describe	Lists active DataCanvas dataframes created by prior eia_query_route calls. Shows table name, column names and types, row count, and canvas ID.
eia_dataframe_query	Runs a read-only SQL SELECT against a DataCanvas dataframe by canvas ID or table name.
eia_dataframe_drop	Drops a DataCanvas dataframe, freeing its memory. Only exposed when EIA_DATAFRAME_DROP_ENABLED=true.

eia_browse_routes

Walk the EIA dataset taxonomy from root to leaf.

• Root call returns 14 top-level categories: electricity, petroleum, natural-gas, coal, international, total-energy, steo, aeo, ieo, seds, crude-oil-imports, nuclear-outages, densified-biomass, co2-emissions
• Intermediate paths return subcategories; leaf routes are flagged so callers know when to switch to eia_describe_route
• STEO (Short-Term Energy Outlook) is a flat leaf with 1,469 named series — no sub-routes

---

eia_describe_route

Full schema for a leaf route. Required before constructing facet filters.

• Returns facets with valid values (fetched via per-facet API calls and cached in-process)
• Returns data column names, units, frequency options, and date range
• eia_search_routes and eia_browse_routes resolve the route path; this tool provides the filter vocabulary

---

eia_search_routes

Fuzzy search across the in-memory route index.