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.
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.
Tool Definition Quality
Average 4.7/5 across 6 of 6 tools scored.
Each tool has a distinct purpose: browsing taxonomy, describing routes, querying data, searching routes, and managing dataframes. No overlapping functionality.
Most tools follow a verb_noun pattern (e.g., browse_routes, query_route), but dataframe_describe and dataframe_query invert to noun_verb, causing a minor inconsistency.
With 6 tools, the set covers the full exploration and analysis workflow without being excessive or insufficient.
The tools enable a complete workflow: discover routes (browse/search), inspect metadata (describe), fetch data (query), and perform SQL analysis (dataframe query/describe). No critical gaps.
Available Tools
6 toolseia_browse_routesBrowse EIA RoutesARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Route path to browse (e.g. "electricity", "petroleum/pri"). Omit for root. |
Output Schema
| Name | Required | Description |
|---|---|---|
| path | Yes | The path that was browsed (empty string for root). |
| isLeaf | Yes | True when the browsed path itself is a leaf route — no children to drill into; use eia_describe_route instead. |
| children | Yes | Child entries under the browsed path. |
Tool Definition Quality
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.
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.
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.
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.
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.
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 DataframesARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | df_<id> handle to describe a single dataframe. Omit to list all active dataframes. |
Output Schema
| Name | Required | Description |
|---|---|---|
| dataframes | Yes | Active dataframes for this tenant, newest first. Empty when none are registered. |
Tool Definition Quality
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.
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.
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.
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.
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.
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 DataframesARead-onlyIdempotentInspect
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 at the bridge layer. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | 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 | No | Rows 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_limit | No | Hard cap on rows materialized in the response (default 1000, max 10000). | |
| register_as | No | When 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
| Name | Required | Description |
|---|---|---|
| rows | Yes | Materialized rows, bounded by preview / row_limit. |
| columns | Yes | Column names in projection order. |
| row_count | Yes | Total rows the query produced (may exceed rows.length when capped). |
| expires_at | No | ISO 8601 expiry for the newly registered dataframe, when applicable. |
| registered_as | No | Set when register_as was supplied and the new dataframe was materialized. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description goes beyond by listing rejected operations (writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file table functions), denying system catalogs, noting that EIA values are VARCHAR requiring CAST, and explaining the register_as option. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every sentence is informative, front-loaded with the core purpose. Minor redundancy in repeating 'df_<id>' but overall efficient and well-structured. Still, a slight reduction in length could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (SQL query), 100% schema coverage, annotations, and an output schema (not shown but present), the description covers read-only restrictions, data type handling, registration option, and references. It is complete for an agent to properly use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra context: an example query for 'sql', usage guidance for 'preview' when chaining, default and max for 'row_limit', and purpose and conflict behavior for 'register_as'. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs SELECT queries on canvas dataframes registered by eia_query_route, using DuckDB SQL. It distinguishes from siblings like eia_query_route (likely loads data) and eia_dataframe_describe (describes dataframes) by specifying the tool's function and limitations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (after registering dataframes via eia_query_route) and what operations are rejected (writes, DDL, etc.). It references dataframes by df_<id> handles and gives an example. However, it does not explicitly contrast with sibling tools or provide specific when-not-to-use guidance, making it a 4.
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 RouteARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| route | Yes | Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes. |
Output Schema
| Name | Required | Description |
|---|---|---|
| route | Yes | The route path described. |
| facets | Yes | Filterable dimensions. Each facet has an ID and a set of valid values. |
| date_range | Yes | Available date range for this route. |
| description | Yes | Human-readable description of the dataset. |
| frequencies | Yes | Valid frequency options for eia_query_route. |
| data_columns | Yes | Data columns available for this route. |
| default_frequency | Yes | Default frequency ID used when none is specified. |
| default_date_format | Yes | Period format for the default frequency (e.g. "YYYY-MM"). |
Tool Definition Quality
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.
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.
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.
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.
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.
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 DataARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | Period end (same format as start). | |
| sort | No | Result ordering. | |
| route | Yes | Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes. | |
| start | No | Period start in the route date format (e.g. "2020-01" for monthly, "2020" for annual). Format from eia_describe_route. | |
| length | No | Rows to fetch per request (default 100, max 5000 per EIA limit). | |
| offset | No | Pagination offset (default 0). | |
| columns | No | Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route. | |
| filters | No | 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. | |
| canvas_id | No | DataCanvas 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. | |
| frequency | No | Aggregation frequency ID (e.g. "monthly", "annual"). Defaults to route default. Valid IDs from eia_describe_route. |
Output Schema
| Name | Required | Description |
|---|---|---|
| data | Yes | Preview 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. |
| route | Yes | The route path queried. |
| total | Yes | Total matching rows in the EIA dataset. |
| dataset | No | df_<id> table handle for the registered dataset — pass directly to eia_dataframe_query SQL (SELECT ... FROM df_<id>). |
| canvas_id | No | Canvas workspace ID — present when spillover occurred or canvas_id was supplied. Pass to subsequent eia_query_route calls to accumulate datasets. |
| frequency | Yes | Frequency of the returned data. |
| date_format | Yes | Period format for the returned data (e.g. "YYYY-MM"). |
| returned_count | Yes | Rows in this response. When returned_count < total, use offset or canvas for the rest. |
| truncation_warning | No | Forwarded from EIA's warnings[] when the API warns of truncated results near the 5,000 per-page limit. |
| canvas_preview_note | No | Human-readable note when total > returned rows, describing how to access the full dataset via canvas SQL. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals critical behaviors beyond the readOnlyHint: data values are returned as strings requiring casting, large result sets spill to a DataCanvas table, and the canvas_id mechanism for accumulation. Annotations only mark it as read-only, so this adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences, each adding distinct value: core action, prerequisite, behavioral note on data types, handling of large results, and accumulation mechanism. No redundancy or wordiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, nested objects) and existence of an output schema, the description covers essential aspects: data type handling, canvas integration, prerequisites, and alternatives. Minor omission of error or auth details, but overall very complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches understanding by explaining the canvas_id lifecycle, date format examples, default behaviors for columns and frequency, and that filters use facet IDs from eia_describe_route. This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with the specific verb 'Fetches data from a leaf route' and clearly identifies the resource and action. It distinguishes the tool from siblings by advising to use eia_describe_route first for discovery and eia_dataframe_query for large result sets, making its unique role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: use eia_describe_route first to obtain valid IDs, use eia_dataframe_query for SQL analysis on large results, and pass canvas_id to accumulate multiple route results for cross-route joins. This covers when to use the tool and when to use alternatives.
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 RoutesARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (default 10, max 30). | |
| query | Yes | Free-text search terms to match against route names and descriptions. |
Output Schema
| Name | Required | Description |
|---|---|---|
| results | Yes | Ranked matches, best first. |
| total_indexed | Yes | Total entries in the search index (routes + STEO series names). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, but description adds behavioral context: fuzzy matching, index includes STEO series, results include isLeaf, and score threshold for weak matches. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all essential. Front-loaded with purpose, examples, and actionable guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description need not detail returns. It covers search behavior, weak match interpretation, and links to sibling tool. Complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). Description adds value by explaining the fuzzy search nature and output fields (isLeaf, score), but doesn't add new parameter-level syntax beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs fuzzy text search across route names, descriptions, and category labels, resolving natural-language queries. Distinguishes from siblings by mentioning isLeaf and score, and references eia_browse_routes for alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (fuzzy search, natural-language queries) and when not to (weak matches >0.5 suggest more specific query or eia_browse_routes). Uses concrete examples like 'electricity retail sales by state'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!