Tools

Four route tools cover the two-phase EIA workflow — find the right dataset route, then pull the data. Three DataCanvas tools add SQL over staged results and are listed only where a canvas is configured (CANVAS_PROVIDER_TYPE=duckdb); eia_dataframe_drop needs its own opt-in on top. A default deployment therefore advertises four tools, all of them working:

eia_browse_routes

Walk the EIA dataset taxonomy from root to leaf.

• Root call returns 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
• Intermediate paths return subcategories; leaf routes are flagged so callers know when to switch to eia_describe_route
• STEO (Short-Term Energy Outlook) is a flat leaf with 1,469 named series — no sub-routes

eia_describe_route

Full schema for a leaf route. Required before constructing facet filters.

• Returns facets with valid values (fetched via per-facet API calls and cached in-process)
• Returns data column names, units, frequency options, and date range
• Each facet returns at most EIA_FACET_VALUE_CAP values, alongside value_count and values_truncated. Pass facet with values_offset to page one facet past the cap — the cap shapes this tool's response only, and the in-process cache keeps every value
• That window is the same on both client surfaces: content[] renders every value structuredContent carries, so both name the same next call
• values_offset applies to every facet in the response. One past a facet's last value empties that facet's window and returns a notice naming the facet and its value_count, so an overshoot never reads like a fully enumerated facet
• In content[] a value reads as id=name (alias), with the alias left off when it only restates the pair — EIA supplies (IN) Indiana beside IN=Indiana on most values. An alias that adds something, such as Region: (MAT) Middle Atlantic, still prints, and the alias field itself is unchanged
• A value EIA sends without a name is labelled from its alias, then from its id — the id is what filters, so the value is kept. A value EIA sends without an id is dropped, having nothing to filter with
• eia_search_routes and eia_browse_routes resolve the route path; this tool provides the filter vocabulary

eia_search_routes

Fuzzy search across the in-memory route index.

• Indexes route names, descriptions, and category labels — plus STEO's 1,469 series names and facet values
• Resolves natural language ("natural gas spot prices", "ethanol net imports") to queryable route paths, and a fuel-type or sector term ("wind", "anthracite coal") to the route that exposes it, with a filter_hint to pass straight to eia_query_route
• A multi-term query is 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. Each result keeps the better of its whole-phrase and per-term score; a single-term query takes the phrase path alone
• score runs 0 (exact) to 1 (no match), lower is better; above 0.72 the match is unreliable and the query is worth narrowing. bun run eval:search scores a labelled query battery against a live corpus, which is where that number comes from
• The first call waits for the whole corpus to warm — 24–30 s measured against the live API from cold, and never more than 45 s, so a degraded upstream cannot hold the call past a client's request timeout. Every later search is served from the in-process Fuse.js index in tens of milliseconds, with no upstream cost
• indexComplete reports whether the answer was ranked against the whole corpus; when it is false, indexGaps names the routes and index passes that are missing, so a short result set is never mistaken for a settled one

eia_query_route

Pull data from a leaf route.

• Facet filters keyed by facet ID (e.g. { "stateid": "TX", "sectorid": ["RES", "COM"] })
• Date range and frequency selection; valid values discoverable via eia_describe_route
• Pagination via offset/length (max 5,000 rows per page); total row count in response
• All numeric values arrive as strings from the EIA API — units appear as inline {col}-units fields per row
• Route paths accept leading, trailing, and doubled slashes — an EIA-doc spelling like /electricity/retail-sales/ resolves to the same route, and the response echoes the canonical form back
• DataCanvas staging is opt-in per call via stage: true: further pages are fetched and the accumulated rows are staged as a dataset (df_<id>) for SQL, bounded by EIA_CANVAS_MAX_ROWS. The response note names how many rows actually reached the table. Left off (the default), a query costs one upstream request however large the match is, and the note names stage: true as the way to reach the rest.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

EIA-specific:

• Full coverage of EIA API v2 — all 14 top-level dataset categories
• In-process route tree cache with Fuse.js fuzzy index — built once on first use at a paced request rate, no repeated upstream calls
• Facet values are searchable: a bounded pass indexes the fuel-type, sector, and technology vocabulary named in the route tree, and every described route folds its own values in at no upstream cost
• Warm gaps are tracked, not swallowed: a route whose metadata could not be fetched is held as an incomplete stub rather than passed off as a queryable leaf, reported through eia_search_routes, and re-fetched by the next eia_browse_routes call that reaches it
• Per-route facet cache via Promise.all fan-out — valid filter values available without re-fetching
• STEO series names (1,469 entries) indexed for natural-language discovery
• DataCanvas (DuckDB) opt-in for tabular staging — the three dataframe tools are gated at registration, so a canvas-less deployment lists no tool it cannot serve

Getting started

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

Running the server

Local development

• Build and run:

  sh

  Copy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  sh

  Copy

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

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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.