@cyanheads/eia-energy-mcp-server

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

The three eia_dataframe_* tools are registered only when CANVAS_PROVIDER_TYPE=duckdb is set; eia_dataframe_drop additionally requires EIA_DATAFRAME_DROP_ENABLED=true. A default deployment lists the first four tools.

Related MCP server: @cyanheads/federal-reserve-mcp-server

Capability reference

eia_browse_routes tool

• Omit path for the 14 top-level categories (electricity, petroleum, natural-gas, coal, international, total-energy, steo, aeo, ieo, seds, crude-oil-imports, nuclear-outages, densified-biomass, co2-emissions); pass a path to drill into subcategories

• Each child carries isLeaf — leaf routes are queryable via eia_describe_route / eia_query_route; non-leaf routes have further children to browse

• steo is a flat leaf with 1,469 named series and no sub-routes

• Accepts route as an alias for path; supplying both is rejected. Leading, trailing, and doubled slashes are stripped before resolving

• route_not_found when the path does not exist in the taxonomy

eia_describe_route tool

• Returns facets (with valid values), data column names/units, frequency options, and date range for a leaf route; accepts path as an alias, but not alongside route

• Each facet is capped at EIA_FACET_VALUE_CAP values (default 50), with value_count and values_truncated; page one facet with facet + values_offset

• A values_offset past a facet's last value returns an empty window plus a notice naming the facet and its value_count, rather than reading as an exhausted enumeration

• Errors: route_not_found, route_not_queryable (category node, not a leaf), facet_not_found, rate_limited (retryable)

eia_search_routes tool

• Fuzzy match over route names/descriptions, STEO's 1,469 series names, and facet values; limit caps results (default 10, max 30)

• score runs 0 (exact) to 1 (no match); above 0.72 is a weak match — narrow the query or use eia_browse_routes

• Matching facet-value or STEO results carry filter_hint, a ready-to-use filter object for eia_query_route

• The first call after server start waits 24–30 s (never more than 45 s) for the index to warm; every later call is served from the in-process index in milliseconds

• indexComplete / indexGaps report whether the corpus was complete when scored — check before trusting a short result set

eia_query_route tool

• Takes route (or alias path, never both), facet filters keyed by facet ID (from eia_describe_route), plus optional columns, frequency, start/end, and sort

• offset/length page the inline preview (length default 100, max 5000 per EIA's per-request ceiling); total reports the full match count

• Data values arrive as strings; per-column units appear as inline {col}-units fields

• stage: true pages past the preview and stages the accumulated rows as a DataCanvas df_<id> table (bounded by EIA_CANVAS_MAX_ROWS, default 25000) for eia_dataframe_query; omitted, the call costs one upstream request regardless of total

• Errors: route_not_found, route_not_queryable, invalid_facet / invalid_column / invalid_frequency / invalid_sort / invalid_period, no_data (inverted date range), rate_limited (retryable)

eia_dataframe_describe tool

• Lists DataCanvas dataframes staged by prior eia_query_route calls with stage: true; only registered when CANVAS_PROVIDER_TYPE=duckdb

• Omit name to list every active dataframe for the tenant; pass name to check one — a miss comes back as found: false alongside active_names, never as an empty list

• Each entry reports source_tool, query_params, created_at, expires_at, row_count, truncated / max_rows, and column_schema

• Listing does not extend a dataframe's expiry — only an eia_dataframe_query statement referencing it does

• canvas_unavailable when no canvas is configured

eia_dataframe_query tool

• Runs one read-only SQL SELECT against df_<id> tables; writes, DDL, DROP, COPY, PRAGMA, ATTACH, and system catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are rejected

• row_limit (default 1000, max 10000) hard-caps materialized rows — rows past it are dropped uncounted, so totalRows becomes the cap, not a true total; preview separately narrows the inline slice without affecting the count

• register_as persists the result as a new dataframe with a fresh expiry; the name must be unused

• EIA data columns are VARCHAR — cast with CAST(col AS DOUBLE) for arithmetic

• Errors: canvas_unavailable, system_catalog_access, missing_table, non_select_statement, invalid_sql, register_as_clash

eia_dataframe_drop tool

• Drops a dataframe by name; idempotent — returns dropped: false when nothing matched

• Only registered when EIA_DATAFRAME_DROP_ENABLED=true and CANVAS_PROVIDER_TYPE=duckdb

• Manual cleanup only — the per-dataframe expiry (default 24 h, extended by every referencing query) handles cleanup in normal operation

• canvas_unavailable when no canvas is configured

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; the three dataframe tools are gated at registration so a canvas-less deployment lists no tool it cannot serve

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:

{
  "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.

{
  "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):

{
  "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:

{
  "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

1. Clone the repository:

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

2. Navigate into the directory:

cd eia-energy-mcp-server

3. Install dependencies:

bun install

4. 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:

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

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.