Skip to main content
Glama

eia-energy-mcp-server

Server Details

Browse and query the EIA API v2 — electricity, petroleum, natural gas, coal, forecasts via MCP.

Status
Healthy
Last Tested
Transport
Streamable HTTP
URL
Repository
cyanheads/eia-energy-mcp-server
GitHub Stars
1

Glama MCP Gateway

Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.

MCP client
Glama
MCP server

Full call logging

Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.

Tool access control

Enable or disable individual tools per connector, so you decide what your agents can and cannot do.

Managed credentials

Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.

Usage analytics

See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.

100% free. Your data is private.
Tool DescriptionsA

Average 4.8/5 across 6 of 6 tools scored.

Server CoherenceA
Disambiguation5/5

Each tool has a clearly distinct purpose: browsing taxonomy, searching routes, describing endpoints, querying data, and managing dataframes. No overlaps exist.

Naming Consistency4/5

Most tools follow a verb_noun pattern (e.g., eia_browse_routes), but eia_dataframe_describe and eia_dataframe_query invert the order, creating a minor inconsistency.

Tool Count5/5

With 6 tools, the set is well-scoped for the domain of accessing EIA energy data. Each tool serves a necessary step in the workflow.

Completeness5/5

The tools cover the full workflow: discovery (browse/search), metadata (describe), data retrieval (query), and post-processing (dataframe describe/query). No obvious gaps.

Available Tools

6 tools
eia_browse_routesBrowse EIA RoutesA
Read-only
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoRoute path to browse (e.g. "electricity", "petroleum/pri"). Omit for root.

Output Schema

ParametersJSON Schema
NameRequiredDescription
pathYesThe path that was browsed (empty string for root).
isLeafYesTrue when the browsed path itself is a leaf route — no children to drill into; use eia_describe_route instead.
childrenYesChild entries under the browsed path.
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true; description adds value by explaining the isLeaf flag and hierarchical navigation behavior, though no additional safety details needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the core purpose, then provide drill-down instructions and sibling differentiation without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, annotations cover safety, and description explains the isLeaf flag and transition to sibling tool, making it complete for the browse task.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description enriches the path parameter with usage examples and context (e.g., omit for root), making it more actionable than raw schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool lists child routes under a given path in the EIA dataset taxonomy, with specific examples of top-level categories and explanation of the isLeaf flag, distinguishing it from sibling tools like eia_describe_route.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to start with no path for top-level categories, then drill into subcategories, and conditionally switch to eia_describe_route when isLeaf is true, providing clear when-to and when-not-to use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

eia_dataframe_describeDescribe EIA DataframesA
Read-onlyIdempotent
Inspect

List canvas dataframes (df_) materialized by eia_query_route, with provenance, TTL, row count, and column schema. Lazy-sweeps expired tables 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNodf_<id> handle to describe a single dataframe. Omit to list all active dataframes.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataframesYesActive dataframes for this tenant, newest first. Empty when none are registered.
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds value beyond annotations by disclosing the lazy-sweep of expired tables, ensuring the list is current, matching readOnlyHint and idempotentHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-loaded with the core action, no unnecessary words, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity and presence of output schema, description fully covers behavior and return fields, making it complete for agent usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds context on what the returned object includes (provenance, TTL, etc.), going beyond the schema's parameter description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it lists canvas dataframes with provenance, TTL, row count, and column schema, distinguishing from siblings like eia_dataframe_query which queries data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes when to use (list all or inspect specific), but does not explicitly exclude cases or mention alternatives, though context from sibling names provides implicit differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

eia_dataframe_queryQuery EIA DataframesA
Read-onlyIdempotent
Inspect

Run a single-statement SELECT against canvas dataframes registered by eia_query_route. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the df_ handles returned by eia_query_route or listed by eia_dataframe_describe. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions 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 TTL.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesSingle-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
previewNoRows to include in the immediate response. Defaults to row_limit. Set lower when chaining via register_as and only a sample is needed inline.
row_limitNoHard cap on rows materialized in the response (default 1000, max 10000).
register_asNoWhen set, persist the result as a new dataframe with a fresh TTL. Use to chain analyses without re-running upstream queries. Conflicts with an existing name throw Conflict.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYesMaterialized rows, bounded by preview / row_limit.
noticeNoGuidance when results are capped — shows how many rows were omitted.
columnsYesColumn names in projection order.
totalRowsYesTotal rows the query produced (may exceed rows.length when capped by row_limit).
expires_atNoISO 8601 expiry for the newly registered dataframe, when applicable.
executedSqlYesEcho of the SQL statement that was executed — confirms the exact query that ran.
returnedRowsYesRows included in this response.
registered_asNoSet when register_as was supplied and the new dataframe was materialized.
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint and idempotentHint, and the description reinforces the read-only nature by listing rejected operations. It adds details about system catalog denial and VARCHAR data. However, the optional 'register_as' parameter creates a new dataframe, which may conflict with the idempotentHint if used repeatedly with the same name (throws Conflict). This nuance slightly reduces transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that efficiently covers main action, supported features, restrictions, and optional chaining. It is front-loaded but could be slightly better structured with bullet points or clearer separation. Nevertheless, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (DuckDB SQL, multiple parameters, data type handling, optional persistence), the description is thorough. It covers query language scope, rejected operations, data format, parameter meanings, and chaining behavior. Output schema exists, so return values need not be detailed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema: examples for the 'sql' parameter, clarification that 'preview' defaults to row_limit, and explanation of 'register_as' for chaining. These additions improve semantic understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it runs a single-statement SELECT against canvas dataframes, specifying the action (SELECT) and the resource (dataframes registered by eia_query_route). It distinguishes itself from siblings by mentioning how dataframes are obtained (via eia_query_route) and listed (via eia_dataframe_describe), providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use (for SELECT queries on dataframes), what is not supported (writes, DDL, etc.), and provides guidance on data type handling (CAST for arithmetic). It references sibling tools for registration and listing, giving clear context on alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

eia_describe_routeDescribe EIA RouteA
Read-only
Inspect

Returns full 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. Facet values are fetched from separate EIA endpoints and merged — results are cached per-route for the process lifetime to minimize API calls.

ParametersJSON Schema
NameRequiredDescriptionDefault
routeYesLeaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes.

Output Schema

ParametersJSON Schema
NameRequiredDescription
routeYesThe route path described.
facetsYesFilterable dimensions. Each facet has an ID and a set of valid values.
date_rangeYesAvailable date range for this route.
descriptionYesHuman-readable description of the dataset.
frequenciesYesValid frequency options for eia_query_route.
data_columnsYesData columns available for this route.
default_frequencyYesDefault frequency ID used when none is specified.
default_date_formatYesPeriod format for the default frequency (e.g. "YYYY-MM").
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true but the description adds that facet values are fetched from separate endpoints and results are cached per-route for the process lifetime, which is valuable beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, each serving a distinct purpose: stating return values and giving usage guidance plus implementation detail. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and a single parameter, the description covers all necessary context: what the tool returns, how to use it, and an important caching behavior. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a good parameter description. The tool description adds context by mentioning the discoverability of routes via sibling tools and the role of this tool in a workflow, which enhances understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool returns full metadata for a leaf route, listing specific outputs like facets, column names, units, etc. It distinguishes itself from sibling tools by advising to call it before eia_query_route.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use the tool: before eia_query_route to discover valid facet IDs, values, column IDs, and frequency codes. This provides clear contextual guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

eia_query_routeQuery EIA Route DataA
Read-only
Inspect

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; large result sets (total > length) spill to a DataCanvas table when canvas is enabled — use the returned canvas_id and dataset name with eia_dataframe_query for SQL analysis. Pass the same canvas_id on subsequent eia_query_route calls to accumulate multiple route results into one canvas for cross-route joins.

ParametersJSON Schema
NameRequiredDescriptionDefault
endNoPeriod end (same format as start).
sortNoResult ordering.
routeYesLeaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes.
startNoPeriod start in the route date format (e.g. "2020-01" for monthly, "2020" for annual). Format from eia_describe_route.
lengthNoRows to fetch per request (default 100, max 5000 per EIA limit).
offsetNoPagination offset (default 0).
columnsNoData column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route.
filtersNoFacet 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.
canvas_idNoDataCanvas ID to register results into. Omit on first call — a new canvas is minted and returned. Pass the returned canvas_id on subsequent calls to accumulate multiple route results into one canvas for cross-route SQL joins.
frequencyNoAggregation frequency ID (e.g. "monthly", "annual"). Defaults to route default. Valid IDs from eia_describe_route.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataYesPreview rows. All numeric values are strings per the EIA API (e.g. "9.13"). Cast to DOUBLE in SQL for arithmetic: CAST(value AS DOUBLE). Per-column units appear as {col}-units fields inline in each row. Keys are dynamic column IDs from the EIA route.
routeYesThe route path queried.
totalYesTotal matching rows in the EIA dataset for this query (may exceed returned rows when pagination or spillover applies).
noticeNoInformational message when zero rows matched the filters — guidance for broadening the query.
datasetNodf_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>).
canvas_idNoCanvas workspace ID — present when spillover occurred or canvas_id was supplied. Pass to subsequent eia_query_route calls to accumulate datasets.
frequencyYesFrequency of the returned data.
appliedEndNoEcho of the end period as applied, when an end was provided.
totalCountYesTotal matching rows in the EIA dataset.
date_formatYesPeriod format for the returned data (e.g. "YYYY-MM").
appliedStartNoEcho of the start period as applied, when a start was provided.
returnedCountYesRows in this response. When returnedCount < totalCount, use offset or canvas for the rest.
appliedColumnsNoEcho of the column projection as applied, when columns were provided.
appliedFiltersNoFacet filters applied to the query, when provided.
effectiveRouteYesThe route path that was queried.
returned_countYesNumber of rows in this response. When returned_count < total, use offset pagination or DataCanvas for the rest.
appliedFrequencyNoEcho of the frequency as applied, when a frequency was provided.
truncation_warningNoForwarded from EIA's warnings[] when the API warns of truncated results near the 5,000 per-page limit.
canvas_preview_noteNoHuman-readable note when total > returned rows, describing how to access the full dataset via canvas SQL.
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=true), description reveals that data values are returned as strings requiring type casting, and explains preview vs. spill behavior based on result size and canvas enablement. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is comprehensive but well-structured: main action first, then discovery prerequisite, data type caveat, spill behavior, and accumulation guidance. Every sentence adds value, though slightly lengthy due to tool complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, nested objects, and output schema existence, the description covers all necessary aspects: discovery, data types, pagination, canvas accumulation, and SQL workflow integration. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant meaning: explains route path format, canvas_id accumulation pattern, filters object structure using facets.id, and how to discover valid values via eia_describe_route. Each parameter's purpose is clarified beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches data from a leaf route with optional facet filters, date range, frequency, and column selection. It distinguishes from siblings by referencing eia_describe_route for discovery and eia_dataframe_query for SQL analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use eia_describe_route first for valid parameters. Provides context for when to use canvas_id for accumulation and when large results spill to DataCanvas. Offers guidance on handling large result sets and cross-route joins.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

eia_search_routesSearch EIA RoutesA
Read-only
Inspect

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. STEO series names are indexed so queries like "ethanol net imports" or "crude oil production forecast" also resolve. Results include isLeaf so you know whether to browse further or query directly. Results with score > 0.5 are weak matches — try a more specific query or use eia_browse_routes to explore the taxonomy.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results to return (default 10, max 30).
queryYesFree-text search terms to match against route names and descriptions.

Output Schema

ParametersJSON Schema
NameRequiredDescription
capYesThe limit that was applied.
shownYesNumber of results returned.
noticeNoRecovery hint when no routes matched — suggests alternative queries or using eia_browse_routes.
resultsYesRanked matches, best first.
truncatedYesTrue when matches were capped at limit; more may exist.
totalIndexedYesTotal entries in the search index (routes + STEO series names).
effectiveQueryYesQuery as submitted to the Fuse.js index.
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, indicating no destructive behavior. The description adds valuable behavioral context: it performs fuzzy matching, indexes STEO series, and includes isLeaf in results. It also explains how to interpret result scores, which goes beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences long, each sentence adding distinct value: purpose, natural-language capability, STEO indexing, and result interpretation with guidance. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (which likely details return fields), the description covers search behavior, result interpretation, and guidance for weak matches. It also references the sibling tool eia_browse_routes for alternative use, making the context complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage, so baseline is 3. The description adds meaning by specifying that queries are resolved as natural language and that STEO series names are indexed, enhancing the semantic understanding of the query parameter beyond the schema's 'free-text search terms'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool performs fuzzy text search across route names, descriptions, and category labels, resolving natural-language queries to matching route paths. It distinguishes itself from sibling tools like eia_browse_routes by focusing on search rather than browsing the taxonomy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly guides when to use the tool (e.g., for natural-language queries like 'electricity retail sales by state') and when not to (weak matches with score > 0.5 should use a more specific query or switch to eia_browse_routes). This provides clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Discussions

No comments yet. Be the first to start the discussion!

Try in Browser

Your Connectors

Sign in to create a connector for this server.