eia-energy-mcp-server

<div align="center"> <h1>@cyanheads/eia-energy-mcp-server</h1> <p><b>Browse and query the U.S. Energy Information Administration API v2 — electricity, petroleum, natural gas, coal, forecasts, and more via MCP. STDIO or Streamable HTTP.</b> <div>4 core tools + 3 DataCanvas tools</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://eia-energy.caseyjhand.com/mcp

</div>

---

Overview

US energy data from the Energy Information Administration (EIA): electricity, petroleum, natural gas, coal, and forecasts. Find datasets in plain language, query time series with facet filters, and run SQL over large results.

Tools

| Tool | Description | |:-----|:------------| | eia_browse_routes | Lists child routes under a path in the EIA dataset taxonomy; omit path for the 14 top-level categories. | | eia_describe_route | Returns a leaf route's facets, valid values, data columns, frequencies, and date range. | | eia_search_routes | Fuzzy text search across route names, descriptions, STEO and SEDS series names, and facet values — including benchmark series such as Henry Hub, WTI, and Cushing. Resolves legacy APIv1 series IDs (PET.RWTC.W) to their route and filters. | | eia_query_route | Fetches data from a leaf route with facet filters, date range, and column selection; optionally stages results for SQL. | | eia_dataframe_describe | Lists active DataCanvas dataframes staged by eia_query_route, with schema and provenance. | | eia_dataframe_query | Runs a read-only SQL SELECT against staged DataCanvas dataframes. | | eia_dataframe_drop | Drops a DataCanvas dataframe, freeing its memory. |

The three eia_dataframe_* tools need DataCanvas, which is on by default; eia_dataframe_drop additionally requires EIA_DATAFRAME_DROP_ENABLED=true. With CANVAS_PROVIDER_TYPE=none, which the Claude Desktop bundle sets, they are neither callable nor listed by MCP. Disabled definitions remain in the server manifest with their enable hints. A default deployment lists the first six tools.

Capability reference

Browse accepts route as an alias for path; describe and query accept path as an alias for route. Supplying both spellings is rejected. Whitespace and slashes are normalized, then exactly one complete leading v2 segment is removed: /v2/electricity/retail-sales/ resolves to electricity/retail-sales, and /v2/ browses root. Full URLs, /data suffixes, interior v2, and case remain unchanged.

All four route tools distinguish retryable upstream failures: rate_limited for HTTP 429 or OVER_RATE_LIMIT, upstream_unreachable for transport failures, upstream_unavailable for HTTP service outages, upstream_invalid_response for unusable bodies or missing envelopes, and upstream_timeout when EIA does not answer in time — each attempt is cut at 45 s, and a call's attempts, backoffs, and chained requests share one 56 s deadline, inside the 60 s timeout MCP clients apply. Recovery hints reach both response surfaces. HTTP 501 remains definitive, 504 remains a timeout, and caller cancellation stays cancellation.

eia_browse_routes _tool

• Omit path for the 14 top-level categories; pass a path to browse its children.
• Each child carries isLeaf: describe and query leaves, or browse categories further.
• A missing path returns route_not_found; EIA rate-limiting, being unreachable, or not answering in time returns retryable rate_limited, upstream_unreachable, or upstream_timeout.

---

eia_describe_route _tool

• Pass a leaf route for facets, data columns, frequencies, and date range. Each facet window is capped at EIA_FACET_VALUE_CAP (default 50); page with facet and values_offset.
• To find a value by name in a large facet (plant, entity, and mine IDs run to thousands), pass values_query: each facet keeps the values whose id, name, or alias contains it, ignoring case, and values_offset pages the matches. values_query: "palo verde" on electricity/facility-fuel's plantCode returns 6008 and 57773 in one call.
• date_range is metadata for the default frequency; another frequency may extend outside it. Both response surfaces carry this caveat beside the unchanged start/end values.
• value_count, values_truncated, and, with values_query, values_matched describe each window. A facet whose values EIA did not return is listed in unavailable_facets; the next call retries it.
• Errors: route_not_found, route_not_queryable, facet_not_found, and retryable facet_unavailable, rate_limited, upstream_unreachable, upstream_timeout.

---

eia_search_routes _tool

• Search route names, descriptions, STEO's 1,469 and SEDS's 968 series names, and facet values. Before any describe, the facet values cover fuel, sector, technology, and coal-rank vocabularies, RTO balancing authorities (Electric Reliability Council of Texas → respondent: ERCO), and the series and product names of the daily and weekly petroleum and natural-gas routes (Henry Hub → natural-gas/pri/fut, series: RNGWHHD); describing a route adds its own. limit defaults to 10; a larger value returns at most 30 and says so, even on short or empty results. truncated is true when more matches exist. Only the first 256 characters of query are searched, with a notice when it is cut.
• Matches carry score (0 exact, 1 no match; above 0.72 is weak) and may carry a filter_hint for eia_query_route. Check indexComplete and indexGaps before trusting a short result set.
• A legacy APIv1 series ID, as EIA's website and Excel add-in write them, is resolved through EIA's /v2/seriesid lookup before any text search, in any case: ELEC.PRICE.TX-RES.M returns one result, electricity/retail-sales with filter_hint {sectorid: "RES", stateid: "TX"}, frequency: "monthly", and columns: ["price"], ready for eia_query_route. A hit needs no index, so it answers in under a second even on a cold server. When EIA's own lookup reports no rows for the mapping it returns (some AEO IDs), the notice says the query will come back empty. An ID EIA does not recognize (PET.ZZZZZZ.W, or U.S.A, which only looks like one) returns the text search with a notice saying so; a lookup that times out, is rate-limited, or hits an outage does the same with a retry notice, never an error.
• The first search builds the index and normally takes 20–40 s (at most 45 s); later searches answer from the built index. If EIA rate-limits, cannot be reached, or does not answer in time, the call fails with retryable rate_limited, upstream_unreachable, or upstream_timeout.

---

eia_query_route _tool

• Pass a leaf route, with optional facet-ID filters, columns, frequency, start/end, and sort. Page with offset and length (default 25; a larger value returns at most 5,000 and says so).
• Returns length rows per page; continue at next_offset (= offset + returned count).
• After describe has cached a complete facet vocabulary, and for 24 hours after that list was fetched, query notices name unmatched filter values and suggest case-sensitive IDs when possible. Filters and their echoes stay unchanged; diagnostics never fetch metadata or facet values.
• With effective monthly YYYY-MM data, a year-only bound means January: end: "2021" stops at 2021-01; use 2021-12 for the full year. Query notices disclose this for either bound without expanding it.
• EIA reads each bound as the period of the effective frequency containing its first day, so start: "2023-01", end: "2023" returns January at monthly. A range is reported as inverted (no_data) only when EIA returns no rows and start selects a later period than end; the message names both periods. At local-hourly each bound needs its hour and UTC offset (2024-02-01T02-06); one without fails as invalid_period before any request. So does a bound naming a date or hour that does not exist in the shape its frequency reads exactly — 2024-02-30 at daily or weekly, 2024-02-01T24 at hourly — since EIA answers those with an HTTP 500 rather than rows.
• total reports the full match count; values remain strings and units appear as {col}-units. Errors cover invalid route, facet, column, frequency, sort, or period, inverted ranges (no_data), a filter list too long for EIA's ~8 KB request URI (uri_too_long; split the values across calls), and retryable rate_limited, upstream_unreachable, and upstream_timeout.
• stage: true stages up to EIA_CANVAS_MAX_ROWS (default 25000) as a dataset handle for SQL via eia_dataframe_describe and eia_dataframe_query (hyphens in column names become underscores). If staging fails, dataset is absent and the note says so. Staging that would run past the call deadline stops before the next page, stages the rows already fetched, and the note says time ran out and gives the offset to resume from.

---

eia_dataframe_describe _tool

• Omit name to list active staged dataframes; pass a handle to inspect one. A miss returns found: false with active_names.
• Entries carry source_tool, query_params, created_at, expires_at, row_count, truncated/max_rows, and column_schema. Listing does not extend expiry.

---

eia_dataframe_query _tool

• Run one read-only SQL SELECT against staged handles. Inline rows follow preview (default 25; a larger value returns at most row_limit and says so, and 0 returns none). row_limit defaults to 1,000 and returns at most 10,000. Echoes (executedSql, columns) come back whole. register_as still stages the complete result.
• truncated: true means totalRows is a cap, not a full count. register_as stages the complete result under an unused name with an exact count; the notice gives the LIMIT/OFFSET query,