Browse and query the EIA API v2 — electricity, petroleum, natural gas, coal, forecasts via MCP.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Lists child routes under a given path in the EIA dataset taxonomy. Start with no path to get the 14 top-level categories (electricity, petroleum, natural-gas, steo, aeo, ieo, seds, etc.), then drill into subcategories. Each result includes an isLeaf flag — leaf routes are queryable endpoints; non-leaf routes have children to browse. When isLeaf is true on the browsed path itself, switch to eia_describe_route. The first call after server start waits up to 20s for the route tree to warm, then answers from EIA directly.
Route path to browse (e.g. "electricity", "petroleum/pri"). Omit for root. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: "/v2/electricity/retail-sales/" resolves to "electricity/retail-sales", and "/v2/" to root. Full URLs and /data suffixes are not normalized.
Lists child routes under a given path in the EIA dataset taxonomy. Start with no path to get the 14 top-level categories (electricity, petroleum, natural-gas, steo, aeo, ieo, seds, etc.), then drill into subcategories. Each result includes an isLeaf flag — leaf routes are queryable endpoints; non-leaf routes have children to browse. When isLeaf is true on the browsed path itself, switch to eia_describe_route. The first call after server start waits up to 20s for the route tree to warm, then answers from EIA directly.
| Argument | Type | Description |
|---|---|---|
| path | string | Route path to browse (e.g. "electricity", "petroleum/pri"). Omit for root. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: "/v2/electricity/retail-sales/" resolves to "electricity/retail-sales", and "/v2/" to root. Full URLs and /data suffixes are not normalized. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"path": {
"type": "string",
"description": "Route path to browse (e.g. \"electricity\", \"petroleum/pri\"). Omit for root. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\", and \"/v2/\" to root. Full URLs and /data suffixes are not normalized."
}
},
"additionalProperties": false
}List canvas dataframes (df_<id>) materialized by eia_query_route calls that passed stage: true, with provenance, expiry, row count, and column schema. Nothing is staged until such a call runs, so an empty list on a fresh session means no query has staged yet, not that staging failed. Drops entries for dataframes the canvas no longer holds before responding, so the list is always current. Pass a specific name to inspect one dataframe; omit to list all active dataframes for this tenant. A name that is not staged comes back as found=false alongside the handles that are, never as an empty list. Listing is not use: only an eia_dataframe_query statement naming a dataframe extends its expiry, so a dataframe polled with this tool and never queried still lapses on schedule.
| Argument | Type | Description |
|---|---|---|
| name | string | df_<id> handle to describe a single dataframe. Omit to list all active dataframes. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"name": {
"type": "string",
"description": "df_<id> handle to describe a single dataframe. Omit to list all active dataframes."
}
},
"additionalProperties": false
}Run a single-statement SELECT against canvas dataframes registered by eia_query_route calls that passed stage: true — a query that staged nothing leaves no table to select from. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the df_<id> handles returned by eia_query_route or listed by eia_dataframe_describe. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, file reads (read_* functions or a quoted file path), engine-setting functions (current_setting), and SQL built from a string (query_table) are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied. EIA data values are VARCHAR — use CAST(col AS DOUBLE) for arithmetic and aggregation. Optional register_as chains results as a new dataframe with a fresh expiry. Every dataframe named in the statement has its expiry extended by the query. Inline rows stop at a 64,000-byte budget per response surface; a result cut short says how to page the rest from a register_as table with ORDER BY … LIMIT/OFFSET.
| Argument | Type | Description |
|---|---|---|
| sql* | string | Single-statement SELECT against df_<id> tables. EIA data columns are VARCHAR — use CAST(col AS DOUBLE) for arithmetic. Example: SELECT period, CAST(value AS DOUBLE) AS val FROM df_XXXXX ORDER BY period |
| preview | integer | Rows to include in the immediate response. Defaults to row_limit; larger integers are clamped to 10000 with a notice. Set lower when chaining via register_as and only a sample is needed inline. The 64,000-byte response budget can end the inline rows sooner. |
| row_limit | integer | Hard cap on rows materialized (default 1000; larger integers are clamped to 10000 with a notice). Rows past the cap are dropped without being counted — the response then carries truncated: true and a totalRows equal to the cap rather than a true total. Pass register_as to materialize the whole result instead and get an exact count. Of the rows materialized, only as many go inline as fit the 64,000-byte response budget. |
Returns metadata for a leaf route: available facets with their valid values, data column names and units, frequency options, and date range. Call this before eia_query_route to discover valid facet IDs, facet values, column IDs, and frequency codes. Each facet returns a capped window of its values with value_count and values_truncated alongside; pass facet and values_offset to page through the rest of one facet. To find a value by name in a large facet (plant, entity, and mine IDs run to thousands), pass values_query: each facet keeps only the values whose id, name, or alias contains it, values_matched counts them, and values_offset pages the matches. A values_offset past the last value of a facet returns an empty window for it and a notice naming the count to page against. Facet values are fetched from separate EIA endpoints, merged, and cached per route; a facet whose values EIA did not return is left out of facets, named in unavailable_facets, and fetched again by the next call.
| Argument | Type | Description |
|---|---|---|
| facet | string | Restrict the response to one facet by ID (e.g. "stateid"). Use with values_offset to page a facet whose values were truncated, or with values_query to find a value in it. Omit to get every facet. |
| route* | string | Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: "/v2/electricity/retail-sales/" resolves to "electricity/retail-sales". Full URLs and /data suffixes are not normalized. |
| values_query | string | Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. "palo verde" on plantCode). A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value. |
Fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. Use eia_describe_route first to discover valid facet IDs, facet values, column IDs, and frequency codes. Data values are strings in the response (EIA API returns all numeric values as strings, e.g. "9.13"); cast to DOUBLE in SQL when arithmetic is needed. Returns a preview inline and stages nothing by default — one upstream request, whatever total says. Pass stage: true to also page past the preview and stage the accumulated set as a DataCanvas table, then pass the returned dataset name to eia_dataframe_describe for its column names and eia_dataframe_query for SQL. Every dataset a tenant stages lands in the same canvas, so tables from different routes cross-join by name with nothing to thread between calls.
| Argument | Type | Description |
|---|---|---|
| end | string | Period end, read the same way as start: a coarser end selects only its first period, so "2020" ends at 2020-01 at monthly — use "2020-12" to include the whole year. At hourly a date-only end covers its whole day. |
| sort | array | Result ordering. |
| route* | string | Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: "/v2/electricity/retail-sales/" resolves to "electricity/retail-sales". Full URLs and /data suffixes are not normalized. |
| stage | boolean | Stage the matching rows as a DataCanvas table for SQL (default false). Off, the call makes one upstream request and returns the preview alone. On, the service pages past the preview up to EIA_CANVAS_MAX_ROWS and registers the accumulated rows, returning the handle in dataset — several extra upstream requests and seconds of latency on a large route, so turn it on when moving to analysis, not while exploring. Requires a canvas, which is on unless the server sets CANVAS_PROVIDER_TYPE=none; without one nothing is staged whatever this is set to. |
Fuzzy text search across route names, descriptions, and category labels. Resolves natural-language queries like "electricity retail sales by state" or "natural gas imports" to matching route paths. Multi-term queries are also matched term by term, so combining a commodity, a metric, and a sector — "electricity price residential", "coal generation industrial sector" — reaches the route carrying that data even when no single entry reads like the whole phrase. A query spelling the end of a route path in words — "retail sales" for electricity/retail-sales — ranks that route first. STEO and SEDS series names are indexed so queries like "crude oil production forecast" or "motor gasoline total consumption" also resolve, and so are facet values, so a fuel type or sector term like "wind" or "anthracite coal" resolves to the route that exposes it, with filter_hint carrying the filter to pass on. That includes the series and product names of the daily and weekly petroleum and natural-gas routes and the RTO balancing authorities, so benchmarks like "Henry Hub", "WTI crude spot price", "Cushing", or "Electric Reliability Council of Texas" resolve before any describe. A legacy APIv1 series ID as the EIA website and Excel add-in write them — "PET.RWTC.W", "ELEC.PRICE.TX-RES.M" — is resolved through the EIA series lookup into one result with its route, filter_hint, frequency, and columns, ready for eia_query_route, without waiting on the index. Results include isLeaf so you know whether to browse further or query directly. Results with score > 0.72 are weak matches — try a more specific query or use eia_browse_routes to explore the taxonomy. The first call after server start waits 20-40s while the index warms, and at most 45s; later calls answer from the built index. Check indexComplete before reading anything into a short or empty result set.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Maximum results to return (default 10). One call returns at most 30; a larger limit is served at 30, and truncated says whether more matches exist. |
| register_as | string | When set, persist the result as a new dataframe with a fresh expiry. Use to chain analyses without re-running upstream queries. The name must be unused — reusing a staged name is rejected, and the fix is a different name, not dropping the existing dataframe. eia_dataframe_describe lists the names already taken. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "string",
"minLength": 1,
"description": "Single-statement SELECT against df_<id> tables. EIA data columns are VARCHAR — use CAST(col AS DOUBLE) for arithmetic. Example: SELECT period, CAST(value AS DOUBLE) AS val FROM df_XXXXX ORDER BY period"
},
"preview": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows to include in the immediate response. Defaults to row_limit; larger integers are clamped to 10000 with a notice. Set lower when chaining via register_as and only a sample is needed inline. The 64,000-byte response budget can end the inline rows sooner."
},
"row_limit": {
"type": "integer",
"default": 1000,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Hard cap on rows materialized (default 1000; larger integers are clamped to 10000 with a notice). Rows past the cap are dropped without being counted — the response then carries truncated: true and a totalRows equal to the cap rather than a true total. Pass register_as to materialize the whole result instead and get an exact count. Of the rows materialized, only as many go inline as fit the 64,000-byte response budget."
},
"register_as": {
"type": "string",
"minLength": 1,
"description": "When set, persist the result as a new dataframe with a fresh expiry. Use to chain analyses without re-running upstream queries. The name must be unused — reusing a staged name is rejected, and the fix is a different name, not dropping the existing dataframe. eia_dataframe_describe lists the names already taken."
}
},
"additionalProperties": false
}| values_offset | integer | Index of the first facet value to return, applied to every facet in the response. Use the value named in a truncation hint to continue past the cap. With values_query, indexes the matching values. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"route"
],
"properties": {
"facet": {
"type": "string",
"minLength": 1,
"description": "Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated, or with values_query to find a value in it. Omit to get every facet."
},
"route": {
"type": "string",
"minLength": 1,
"description": "Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\". Full URLs and /data suffixes are not normalized."
},
"values_query": {
"type": "string",
"minLength": 1,
"description": "Keep only the facet values whose id, name, or alias contains this text, ignoring case (e.g. \"palo verde\" on plantCode). A plain substring match, not a pattern or a ranked search. Applied to every facet in the response, before values_offset and the cap. Leading and trailing whitespace is ignored. Omit to list every value."
},
"values_offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Index of the first facet value to return, applied to every facet in the response. Use the value named in a truncation hint to continue past the cap. With values_query, indexes the matching values."
}
},
"additionalProperties": false
}| start | string | Period start in the route date format (e.g. "2020-01" for monthly, "2020" for annual). Format from eia_describe_route. EIA reads a bound as the period of the effective frequency containing its first day, so a coarser bound selects that one period ("2020" is 2020-01 at monthly, "2020-Q4" is 2020-10). At local-hourly every bound needs its hour and UTC offset (YYYY-MM-DDTHH±HH, e.g. "2024-02-01T02-06"). |
| length | integer | Rows to fetch for the inline page (default 100; larger integers are clamped to 5000 with a notice). Every fetched row is used, but the response carries only as many as fit a 64,000-byte budget per surface — wide routes end the page early, said so in canvas_preview_note, with next_offset naming where to continue. With stage: true, staging is not bounded by this — it pages past the preview on its own. |
| offset | integer | Row offset into the matching set (default 0). An offset at or beyond total returns zero rows. |
| columns | array | Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route data_columns[].id. Every row also carries period and each facet ID whatever this lists, so naming those here is unnecessary and they are dropped from the request. |
| filters | object | Facet filters keyed by facet ID (e.g. { "stateid": "TX", "sectorid": ["RES", "COM"] }). Use the facets[].id values returned by eia_describe_route as keys here. Every value travels in the request URI, which EIA caps at about 8 KB — a few hundred values across all filters; split a longer list across calls. |
| frequency | string | Aggregation frequency ID (e.g. "monthly", "annual"). Defaults to route default. Valid IDs from eia_describe_route. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"route"
],
"properties": {
"end": {
"type": "string",
"description": "Period end, read the same way as start: a coarser end selects only its first period, so \"2020\" ends at 2020-01 at monthly — use \"2020-12\" to include the whole year. At hourly a date-only end covers its whole day."
},
"sort": {
"type": "array",
"items": {
"type": "object",
"required": [
"column",
"direction"
],
"properties": {
"column": {
"type": "string",
"description": "Column ID to sort by."
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort direction."
}
},
"description": "A sort criterion."
},
"description": "Result ordering."
},
"route": {
"type": "string",
"minLength": 1,
"description": "Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Whitespace and slashes are normalized, then one complete leading v2 segment is removed: \"/v2/electricity/retail-sales/\" resolves to \"electricity/retail-sales\". Full URLs and /data suffixes are not normalized."
},
"stage": {
"type": "boolean",
"default": false,
"description": "Stage the matching rows as a DataCanvas table for SQL (default false). Off, the call makes one upstream request and returns the preview alone. On, the service pages past the preview up to EIA_CANVAS_MAX_ROWS and registers the accumulated rows, returning the handle in dataset — several extra upstream requests and seconds of latency on a large route, so turn it on when moving to analysis, not while exploring. Requires a canvas, which is on unless the server sets CANVAS_PROVIDER_TYPE=none; without one nothing is staged whatever this is set to."
},
"start": {
"type": "string",
"description": "Period start in the route date format (e.g. \"2020-01\" for monthly, \"2020\" for annual). Format from eia_describe_route. EIA reads a bound as the period of the effective frequency containing its first day, so a coarser bound selects that one period (\"2020\" is 2020-01 at monthly, \"2020-Q4\" is 2020-10). At local-hourly every bound needs its hour and UTC offset (YYYY-MM-DDTHH±HH, e.g. \"2024-02-01T02-06\")."
},
"length": {
"type": "integer",
"default": 100,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Rows to fetch for the inline page (default 100; larger integers are clamped to 5000 with a notice). Every fetched row is used, but the response carries only as many as fit a 64,000-byte budget per surface — wide routes end the page early, said so in canvas_preview_note, with next_offset naming where to continue. With stage: true, staging is not bounded by this — it pages past the preview on its own."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Row offset into the matching set (default 0). An offset at or beyond total returns zero rows."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route data_columns[].id. Every row also carries period and each facet ID whatever this lists, so naming those here is unnecessary and they are dropped from the request."
},
"filters": {
"type": "object",
"description": "Facet filters keyed by facet ID (e.g. { \"stateid\": \"TX\", \"sectorid\": [\"RES\", \"COM\"] }). Use the facets[].id values returned by eia_describe_route as keys here. Every value travels in the request URI, which EIA caps at about 8 KB — a few hundred values across all filters; split a longer list across calls.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"frequency": {
"type": "string",
"description": "Aggregation frequency ID (e.g. \"monthly\", \"annual\"). Defaults to route default. Valid IDs from eia_describe_route."
}
},
"additionalProperties": false
}| query* |
| string |
| Free-text search terms to match against route names and descriptions, or a legacy APIv1 series ID (e.g. "PET.RWTC.W": three or more dot-separated segments ending in a frequency code A, Q, M, W, D, H, HL, or 4; any case). Leading and trailing whitespace is ignored, and only the first 256 characters are searched. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 9007199254740991,
"minimum": 1,
"description": "Maximum results to return (default 10). One call returns at most 30; a larger limit is served at 30, and truncated says whether more matches exist."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Free-text search terms to match against route names and descriptions, or a legacy APIv1 series ID (e.g. \"PET.RWTC.W\": three or more dot-separated segments ending in a frequency code A, Q, M, W, D, H, HL, or 4; any case). Leading and trailing whitespace is ignored, and only the first 256 characters are searched."
}
},
"additionalProperties": false
}