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

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

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:

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