io.github.cyanheads/eia-energy-mcp-server

Official6 toolsLive

by cyanheads · TypeScript

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

@cyanheads/eia-energy-mcp-server (MCP)

The io.github.cyanheads/eia-energy-mcp-server is an MCP server that lets clients browse and query the U.S. Energy Information Administration (EIA) API v2. It supports electricity, petroleum, natural gas, coal, forecasts, and more, exposing functionality via MCP over STDIO or Streamable HTTP.

🛠️ Key Features

Browse and query EIA API v2 data via MCP
Covers electricity, petroleum, natural gas, coal, and forecasts
Provides 6 tools total

🚀 Use Cases

Retrieve U.S. energy data across multiple commodity and sector categories
Access forecast-related information from EIA API v2 through MCP
Integrate energy data queries into AI agent workflows

⚡ Developer Benefits

Works with Model Context Protocol (MCP) tooling
Supports STDIO or Streamable HTTP transport
Includes TypeScript ecosystem compatibility (and lists Bun)

⚠️ Limitations

Scope is limited to EIA API v2 domains specifically listed (electricity, petroleum, natural gas, coal, forecasts)

Topics

cyanheadseiaelectricityenergy-apienergy-datamcpmcp-servermodel-context-protocolnatural-gaspetroleumtypescriptus-energybuncoalsteoai-agent

Captured live from the server via tools/list.

eia_browse_routes

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.

Parameters1

path

string

optional

Route path to browse (e.g. "electricity", "petroleum/pri"). Omit for root. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like "/electricity/retail-sales/" resolves to the same route.

Raw schema

{
  "type": "object",
  "properties": {
    "path": {
      "description": "Route path to browse (e.g. \"electricity\", \"petroleum/pri\"). Omit for root. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

eia_describe_route

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. 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 and merged — results are cached per-route for the process lifetime to minimize API calls.

Parameters3

route	string	required	Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like "/electricity/retail-sales/" resolves to the same route.
facet	string	optional	Restrict the response to one facet by ID (e.g. "stateid"). Use with values_offset to page a facet whose values were truncated. Omit to get every facet.
values_offset	integer	optional	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.

Raw schema

{
  "type": "object",
  "properties": {
    "route": {
      "type": "string",
      "minLength": 1,
      "description": "Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."
    },
    "facet": {
      "description": "Restrict the response to one facet by ID (e.g. \"stateid\"). Use with values_offset to page a facet whose values were truncated. Omit to get every facet.",
      "type": "string",
      "minLength": 1
    },
    "values_offset": {
      "default": 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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "route"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

eia_search_routes

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. STEO series names are indexed so queries like "ethanol net imports" or "crude oil production forecast" 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. 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 24-30s while the index warms, and at most 45s; every later call returns in milliseconds. Check indexComplete before reading anything into a short or empty result set.

Parameters2

query	string	required	Free-text search terms to match against route names and descriptions.
limit	integer	optional	Maximum results to return (default 10, max 30).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Free-text search terms to match against route names and descriptions."
    },
    "limit": {
      "default": 10,
      "description": "Maximum results to return (default 10, max 30).",
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

eia_query_route

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_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.

Parameters10

route	string	required	Leaf route path (e.g. "electricity/retail-sales", "steo"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like "/electricity/retail-sales/" resolves to the same route.
filters	object	optional	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.
columns	array	optional	Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route.
frequency	string	optional	Aggregation frequency ID (e.g. "monthly", "annual"). Defaults to route default. Valid IDs from eia_describe_route.
start	string	optional	Period start in the route date format (e.g. "2020-01" for monthly, "2020" for annual). Format from eia_describe_route.
end	string	optional	Period end (same format as start).
sort	array	optional	Result ordering.
offset	integer	optional	Row offset into the matching set (default 0). An offset at or beyond total returns zero rows.
length	integer	optional	Rows in the inline preview (default 100, max 5000 per EIA limit). With stage: true, staging is not bounded by this — it pages past the preview on its own.
stage	boolean	optional	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 (CANVAS_PROVIDER_TYPE=duckdb); without one nothing is staged whatever this is set to.

Raw schema

{
  "type": "object",
  "properties": {
    "route": {
      "type": "string",
      "minLength": 1,
      "description": "Leaf route path (e.g. \"electricity/retail-sales\", \"steo\"). Discoverable via eia_browse_routes or eia_search_routes. Leading, trailing, and doubled slashes are stripped, so an EIA-doc spelling like \"/electricity/retail-sales/\" resolves to the same route."
    },
    "filters": {
      "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.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      }
    },
    "columns": {
      "description": "Data column IDs to return (reduces payload). Defaults to all. IDs discoverable via eia_describe_route.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "frequency": {
      "description": "Aggregation frequency ID (e.g. \"monthly\", \"annual\"). Defaults to route default. Valid IDs from eia_describe_route.",
      "type": "string"
    },
    "start": {
      "description": "Period start in the route date format (e.g. \"2020-01\" for monthly, \"2020\" for annual). Format from eia_describe_route.",
      "type": "string"
    },
    "end": {
      "description": "Period end (same format as start).",
      "type": "string"
    },
    "sort": {
      "description": "Result ordering.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "column": {
            "type": "string",
            "description": "Column ID to sort by."
          },
          "direction": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "description": "Sort direction."
          }
        },
        "required": [
          "column",
          "direction"
        ],
        "description": "A sort criterion."
      }
    },
    "offset": {
      "default": 0,
      "description": "Row offset into the matching set (default 0). An offset at or beyond total returns zero rows.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "length": {
      "default": 100,
      "description": "Rows in the inline preview (default 100, max 5000 per EIA limit). With stage: true, staging is not bounded by this — it pages past the preview on its own.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5000
    },
    "stage": {
      "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 (CANVAS_PROVIDER_TYPE=duckdb); without one nothing is staged whatever this is set to.",
      "type": "boolean"
    }
  },
  "required": [
    "route"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

eia_dataframe_describe

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.

Parameters1

name

string

optional

df_<id> handle to describe a single dataframe. Omit to list all active dataframes.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "df_<id> handle to describe a single dataframe. Omit to list all active dataframes.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

eia_dataframe_query

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, 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 expiry. Every dataframe named in the statement has its expiry extended by the query.

Parameters4

sql	string	required	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
register_as	string	optional	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.
preview	integer	optional	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	integer	optional	Hard cap on rows materialized in the response (default 1000, max 10000). 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.

Raw schema

{
  "type": "object",
  "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"
    },
    "register_as": {
      "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.",
      "type": "string",
      "minLength": 1
    },
    "preview": {
      "description": "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "row_limit": {
      "default": 1000,
      "description": "Hard cap on rows materialized in the response (default 1000, max 10000). 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.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md16 KBView on GitHub

@cyanheads/eia-energy-mcp-server

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.

4 core tools + 3 DataCanvas tools

MCP SDK TypeScript

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

Overview

Energy data from the U.S. Energy Information Administration (EIA) API v2 — electricity, petroleum, natural gas, coal, and forecasts. Browse the dataset taxonomy, search it by natural language, and query time-series data with facet filters, then stage large result sets as a SQL-queryable DataCanvas table. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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 series names, and facet values.
`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 are callable and listed by MCP only when CANVAS_PROVIDER_TYPE=duckdb is set; eia_dataframe_drop additionally requires EIA_DATAFRAME_DROP_ENABLED=true. Disabled definitions remain in the server manifest with their enable hints. A default deployment lists the first four 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. Leading, trailing, and repeated slashes are normalized.

`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_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.
value_count and values_truncated describe each window. Errors distinguish route_not_found, route_not_queryable, facet_not_found, and retryable rate_limited.

`eia_search_routes` _tool

Search route names, descriptions, STEO's 1,469 series names, and facet values; limit defaults to 10 and caps at 30.
Matches carry score (0 exact, 1 no match) and may carry a filter_hint for eia_query_route. Scores above 0.72 are weak matches; check indexComplete and indexGaps before trusting a short result set.
The first search waits for the index to warm (normally 24–30 s, at most 45 s); later calls use the in-process index.

`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 100, max 5000).
total reports the full match count; values remain strings and units appear as {col}-units. Errors distinguish invalid route, facet, column, frequency, sort, or period, inverted ranges (no_data), and retryable rate_limited.
stage: true accumulates up to EIA_CANVAS_MAX_ROWS (default 25000) as a dataset handle for eia_dataframe_query; omitted, the call fetches one page.

`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. row_limit defaults to 1000 and caps at 10000; preview narrows the inline slice.
truncated: true means totalRows is the materialization cap, not a full count. register_as stages the complete result under an unused name with an exact count and fresh expiry.
Cast EIA VARCHAR values for arithmetic. Writes and system catalogs are rejected; declared failures include missing_table, invalid_sql, non_select_statement, system_catalog_access, and register_as_clash.

`eia_dataframe_drop` _tool

Pass name to remove a staged dataframe; requires EIA_DATAFRAME_DROP_ENABLED=true.
Returns dropped: false when nothing matched. Manual cleanup is optional: the default 24 h expiry extends whenever a query references the dataframe.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

EIA-specific:

Full coverage of EIA API v2's 14 top-level dataset categories, via an in-process route tree cache built once on first use
Fuzzy search index (Fuse.js) covers route names/descriptions, all 1,469 STEO series names, and facet values for natural-language discovery
Per-route facet metadata is fetched by fan-out (Promise.all) and cached, so eia_query_route filters are validated without re-fetching
A route whose metadata could not be fetched is held as an incomplete stub — reported through eia_search_routes rather than silently dropped — and re-fetched on the next eia_browse_routes call that reaches it
DataCanvas (DuckDB) staging is opt-in per call; a deployment without canvas omits the three dataframe tools from its callable MCP list

Agent-friendly output:

Provenance — eia_query_route echoes the canonical, slash-normalized route rather than the caller's spelling, and every staged dataframe records its source_tool and query_params
Capped-window disclosure — every truncatable response (facet values, row previews, SQL row limits) reports the count against its cap and a notice naming the exact next call to page past it
Discriminated failure — typed error reason values (e.g. route_not_queryable, invalid_facet, missing_table) each carry a recovery hint naming the next tool call

Getting started

Public Hosted Instance

A public instance is available at https://eia-energy.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "eia-energy-mcp-server": {
      "type": "streamable-http",
      "url": "https://eia-energy.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Get a free API key at api.eia.gov, then add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "eia-energy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/eia-energy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "EIA_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "eia-energy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/eia-energy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "EIA_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "eia-energy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "EIA_API_KEY=your-api-key",
        "ghcr.io/cyanheads/eia-energy-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 EIA_API_KEY=your-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
A free EIA API key from api.eia.gov. The DEMO_KEY hits rate limits quickly; a real key is required for sustained use.

Installation

Clone the repository:

git clone https://github.com/cyanheads/eia-energy-mcp-server.git

Navigate into the directory:

cd eia-energy-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env and set required vars (at minimum, EIA_API_KEY)

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`EIA_API_KEY`	Required. Free API key from api.eia.gov — appended as `api_key` on every request.	—
`EIA_BASE_URL`	EIA API base URL.	`https://api.eia.gov/v2`
`EIA_DATASET_TTL_SECONDS`	Sliding per-dataframe TTL in seconds. The window is extended every time an `eia_dataframe_query` statement references the dataframe, so a dataframe stays alive through a long analysis and lapses only once it goes unused for the full interval. Listing it with `eia_dataframe_describe` is not use and does not extend it.	`86400` (24 h)
`EIA_DATAFRAME_DROP_ENABLED`	Set to `true` to expose `eia_dataframe_drop`, which also requires `CANVAS_PROVIDER_TYPE=duckdb`. Off by default to avoid accidental canvas cleanup.	`false`
`EIA_CANVAS_MAX_ROWS`	Cumulative row ceiling for `eia_query_route` canvas staging — five requests at EIA's 5,000-row-per-request ceiling, adding ~8.5 s to a call when it binds. Lower it for snappier exploration, raise it for wider staged analyses.	`25000`
`EIA_FACET_VALUE_CAP`	Facet values `eia_describe_route` returns per facet before truncating. Bounds the response on high-cardinality facets — STEO's `seriesId` alone has 1,469 values. Page past it with the tool's `facet` and `values_offset` inputs.	`50`
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable DataCanvas (Node only). Adds the three `eia_dataframe_*` tools to the surface and lets `eia_query_route` stage rows when called with `stage: true`.	—
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	HTTP server port.	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path.	`/mcp`
`MCP_SESSION_MODE`	HTTP sessions: `stateless`, `stateful`, or `auto` (framework schema default, resolves to `stateful`). This server defaults to `stateless`; an explicit environment value overrides it.	`stateless`
`MCP_PUBLIC_URL`	Public origin override for TLS-terminating reverse-proxy deployments.	—
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`.	`in-memory`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t eia-energy-mcp-server .
docker run --rm -e EIA_API_KEY=your-key -p 3010:3010 eia-energy-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/eia-energy-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and inits services.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`) — browse, describe, search, query, and three DataCanvas dataframe tools.
`src/services/eia`	EIA API v2 service — route tree cache, Fuse.js index, facet fan-out, HTTP client.
`src/services/canvas-bridge`	DataCanvas bridge — registers EIA query results as DuckDB dataframes, routes SQL queries.
`tests/`	Unit and integration tests mirroring `src/`.
`docs/`	Design documents (`design.md`, `idea.md`).

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Always call eia_describe_route before eia_query_route — facet values require a separate API fan-out and are not embedded in route metadata
Wrap EIA responses: validate raw → normalize to domain type → return output schema; data values are strings — never coerce silently

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (6)

eia_browse_routeseia_describe_routeeia_search_routeseia_query_routeeia_dataframe_describeeia_dataframe_query

Configuration

Environment variables

EIA_API_KEYrequired

Free API key from api.eia.gov. Required — all requests use this as the api_key query parameter.

EIA_DATASET_TTL_SECONDSdefault 86400

Sliding per-dataframe TTL in seconds, extended by every query that references the dataframe.

EIA_DATAFRAME_DROP_ENABLEDdefault false

Set to 'true' to expose eia_dataframe_drop for manual canvas cleanup. Also requires CANVAS_PROVIDER_TYPE=duckdb.

EIA_CANVAS_MAX_ROWSdefault 25000

Cumulative row ceiling for eia_query_route DataCanvas staging on a stage: true call. Five requests at EIA's 5000-row-per-request ceiling.

EIA_FACET_VALUE_CAPdefault 50

Facet values eia_describe_route returns per facet before truncating. Page past it with the tool's facet and values_offset inputs.

CANVAS_PROVIDER_TYPE

Set to 'duckdb' to enable DataCanvas (Node.js only). Registers the three eia_dataframe_* tools and lets eia_query_route stage rows when called with stage: true.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_PUBLIC_URL

Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "eia-energy-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/eia-energy-mcp-server@0.4.3"
      ],
      "env": {
        "EIA_API_KEY": "<YOUR_EIA_API_KEY>",
        "EIA_DATASET_TTL_SECONDS": "86400",
        "EIA_DATAFRAME_DROP_ENABLED": "false",
        "EIA_CANVAS_MAX_ROWS": "25000",
        "EIA_FACET_VALUE_CAP": "50",
        "CANVAS_PROVIDER_TYPE": "<YOUR_CANVAS_PROVIDER_TYPE>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/eia-energy-mcp-server (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

eia_browse_routes

eia_describe_route

eia_search_routes

eia_query_route

eia_dataframe_describe

eia_dataframe_query

@cyanheads/eia-energy-mcp-server

Overview

Tools

Capability reference

eia_browse_routes tool

eia_describe_route tool

eia_search_routes tool

eia_query_route tool

eia_dataframe_describe tool

eia_dataframe_query tool

eia_dataframe_drop tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`eia_browse_routes` _tool

`eia_describe_route` _tool

`eia_search_routes` _tool

`eia_query_route` _tool

`eia_dataframe_describe` _tool

`eia_dataframe_query` _tool

`eia_dataframe_drop` _tool