eia-mcp-server

---

概要

米国エネルギー情報局（EIA）のエネルギーデータ：電力、石油、天然ガス、石炭、予測など。平易な言葉でデータセットを探し、ファセットフィルターを使って時系列データを検索し、大量の結果に対して SQL を実行できます。

ツール

ツール	説明
eia_browse_routes	EIA データセットの分類体系におけるパス直下のルートを一覧表示します。14 個の最上位カテゴリを表示するには、path を省略します。
eia_describe_route	リーフルートのファセット、有効な値、データ列、頻度、日付範囲を返します。
eia_search_routes	ルート名、説明、STEO および SEDS の系列名、ファセット値を対象にあいまいテキスト検索を行います。Henry Hub、WTI、Cushing などのベンチマーク系列も検索対象です。従来の APIv1 系列 ID（PET.RWTC.W）を対応するルートとフィルターに解決します。
eia_query_route	ファセットフィルター、日付範囲、列の選択を指定してリーフルートからデータを取得します。必要に応じて SQL 用に結果をステージングします。
eia_dataframe_describe	eia_query_route によってステージングされたアクティブな DataCanvas データフレームを、スキーマと来歴とともに一覧表示します。
eia_dataframe_query	ステージングされた DataCanvas データフレームに対して、読み取り専用の SQL SELECT を実行します。
eia_dataframe_drop	DataCanvas データフレームを削除して、メモリを解放します。

3 つの eia_dataframe_* ツールには DataCanvas が必要です。DataCanvas はデフォルトで有効になっています。eia_dataframe_drop を使うには、さらに EIA_DATAFRAME_DROP_ENABLED=true が必要です。Claude Desktop バンドルで設定される CANVAS_PROVIDER_TYPE=none では、これらのツールは呼び出しも MCP による一覧表示もできません。無効な定義も、有効化のヒントとともにサーバーマニフェストに残ります。デフォルトのデプロイでは、最初の 6 つのツールが一覧表示されます。

機能リファレンス

browse では route を path の別名として指定できます。describe と query では path を route の別名として指定できます。両方の表記を指定すると拒否されます。空白とスラッシュは正規化され、その後、先頭にある完全な v2 セグメントが 1 つだけ削除されます。/v2/electricity/retail-sales/ は electricity/retail-sales として解決され、/v2/ はルートを参照します。完全な URL、/data サフィックス、途中にある v2、大文字と小文字は変更されません。

4 つすべてのルートツールは、再試行可能な上流の障害を区別します。HTTP 429 または OVER_RATE_LIMIT の場合は rate_limited、通信障害の場合は upstream_unreachable、HTTP サービス停止の場合は upstream_unavailable、使用できない本文またはエンベロープの欠落の場合は upstream_invalid_response、EIA が時間内に応答しない場合は upstream_timeout です。各試行は 45 秒で打ち切られ、1 回の呼び出しにおける試行、バックオフ、連鎖リクエストは、MCP クライアントが適用する 60 秒のタイムアウト内に収まる 56 秒の期限を共有します。復旧のヒントは、両方のレスポンス形式で提供されます。HTTP 501 は引き続き確定的なエラー、504 はタイムアウトとして扱われ、呼び出し元によるキャンセルはキャンセルのままです。

eia_browse_routes _ツール

• 14 個の最上位カテゴリを表示するには path を省略します。子ルートを表示するには、パスを指定します。
• 各子には isLeaf が含まれます。リーフでは describe と query を使い、カテゴリではさらに browse を使います。
• パスが見つからない場合は route_not_found が返されます。EIA によるレート制限、到達不能、時間内に応答がない場合は、再試行可能な rate_limited、upstream_unreachable、upstream_timeout が返されます。

---

eia_describe_route _ツール

• ファセット、データ列、頻度、日付範囲を取得するには、リーフの route を指定します。各ファセットのウィンドウには EIA_FACET_VALUE_CAP（デフォルトは 50）の上限があります。facet と values_offset を指定してページを切り替えてください。
• 大きなファセット（発電所、事業体、鉱山の ID は数千件に及びます）から名前で値を検索するには、values_query を指定します。各ファセットでは、id、name、alias のいずれかに指定した文字列が含まれる値を、大文字と小文字を区別せずに抽出し、values_offset で該当結果のページを切り替えます。electricity/facility-fuel の plantCode に対して values_query: "palo verde" を指定すると、1 回の呼び出しで 6008 と 57773 が返されます。
• date_range はデフォルトの頻度に関するメタデータです。別の頻度では、その範囲外のデータが含まれることがあります。この注意書きは、開始値と終了値を変更せずに、両方のレスポンス形式でその隣に表示されます。
• value_count、values_truncated、および values_query を指定した場合の values_matched が、各ウィンドウの情報を示します。EIA が値を返さなかったファセットは unavailable_facets に一覧表示され、次の呼び出しで再試行されます。
• エラー：route_not_found、route_not_queryable、facet_not_found、および再試行可能な facet_unavailable、rate_limited、upstream_unreachable、upstream_timeout。

---

eia_search_routes _ツール

• ルート名、説明、STEO の 1,469 件と SEDS の 968 件の系列名、ファセット値を検索します。ルートを説明する前は、ファセット値として燃料、セクター、技術、石炭ランクの語彙、RTO のバランシング機関（Electric Reliability Council of Texas → respondent: ERCO）、日次および週次の石油・天然ガスルートの系列名と製品名（Henry Hub → natural-gas/pri/fut、series: RNGWHHD）が検索対象になります。ルートを説明すると、そのルート固有の値も追加されます。limit のデフォルトは 10 です。30 を超える正の整数は 30 に制限され、結果が少数または空の場合でも、要求値と適用値が通知されます。一致候補がさらにある場合、truncated は true になります。検索対象となる query の文字数は先頭から 256 文字までで、切り詰められた場合は通知されます。
• 一致候補には score が付与されます（0 は完全一致、1 は一致なし。0.72 を超える場合は一致度が低い）。eia_query_route 用の filter_hint が付与されることもあります。結果が少ない場合は、信頼する前に indexComplete と indexGaps を確認してください。
• EIA のウェブサイトや Excel アドインで使われているレガシー APIv1 系列 ID は、テキスト検索の前に、どのような場合でも EIA の /v2/seriesid 検索で解決されます。ELEC.PRICE.TX-RES.M の場合、filter_hint {sectorid: "RES", stateid: "TX"}、frequency: "monthly"、columns: ["price"] を備えた electricity/retail-sales が 1 件返され、すぐに eia_query_route で使用できます。検索にはインデックスが不要なため、サーバー起動直後でも 1 秒未満で応答します。EIA 独自の検索で、返された対応付けに対する行がないと報告された場合（一部の AEO ID など）は、検索結果が空になるという通知が返されます。EIA が認識しない ID（PET.ZZZZZZ.W、または一見 ID のような U.S.A）の場合は、その旨の通知とともにテキスト検索の結果が返されます。検索がタイムアウトした場合、レート制限された場合、または障害が発生した場合も、エラーではなく、再試行を促す通知とともに同じ結果が返されます。
• 最初の検索ではインデックスが構築され、通常 20～40 秒（最長 45 秒）かかります。それ以降の検索は構築済みのインデックスを使って応答します。EIA によるレート制限、接続不能、または応答の遅延が発生した場合、再試行可能な rate_limited、upstream_unreachable、upstream_timeout のいずれかで呼び出しが失敗します。

---

eia_query_route _tool

• リーフ route を渡します。任意でファセット ID の filters、columns、frequency、start／end、sort を指定できます。offset と length でページングします（デフォルトは 100。5000 を超える正の整数は通知とともに 5000 に制限されます）。
• レスポンスは 64,000 バイト以内に収まります。ページは、収まる最後の完全な行で早期に終了する場合があり、next_offset に続きの開始位置が示されます。1 行が大きすぎて収まらない場合は、その行を除外し、スキップするためのオフセットを注記に示します。
• describe により完全なファセット語彙がキャッシュされた後は、クエリの通知で一致しなかったフィルター値を示し、可能な場合は大文字と小文字を区別する ID を提案します。フィルターとそのエコーは変更されません。診断のためにメタデータやファセット値を取得することはありません。
• 有効な月次 YYYY-MM データでは、年のみの境界は 1 月を意味します。end: "2021" は 2021-01 で終了します。通年分を取得するには 2021-12 を使用します。クエリの通知では、どちらの境界についても展開せずにこの動作を知らせます。
• EIA は、各境界を、その有効な頻度において最初の日が属する期間として扱います。そのため、月次では start: "2023-01", end: "2023" は 1 月を返します。範囲が逆転している（no_data）と報告されるのは、EIA が行を返さず、かつ start が end より後の期間を指定している場合のみです。メッセージには両方の期間が示されます。local-hourly では、各境界に時刻と UTC オフセットが必要です（2024-02-01T02-06）。どちらかがない場合、リクエストを送信する前に invalid_period として失敗します。頻度が正確に読み取る形式で存在しない日付または時刻を指定した境界も同様です。たとえば、daily または weekly での 2024-02-30、hourly での 2024-02-01T24 が該当します。これらに対して EIA は行ではなく HTTP 500 を返すためです。
• total は一致した件数全体を報告します。値は文字列のままで、単位は {col}-units として表示されます。エラーには、無効な route、ファセット、列、頻度、sort、期間、逆転した範囲（no_data）、EIA の約 8 KB のリクエスト URI に収まらない長さのフィルターリスト（uri_too_long。値を複数回の呼び出しに分割してください）、および再試行可能な rate_limited、upstream_unreachable、upstream_timeout が含まれます。
• stage: true を指定すると、最大 EIA_CANVAS_MAX_ROWS（デフォルトは 25000）までを dataset ハンドルとしてステージングし、eia_dataframe_describe と eia_dataframe_query で SQL を実行できます（列名のハイフンはアンダースコアに変換されます）。ステージングに失敗した場合、dataset は存在せず、その旨が注記に示されます。ステージングにより呼び出しの期限を超える場合は、次のページに進む前に停止し、取得済みの行をステージングします。時間切れになったことと、再開するためのオフセットが注記に示されます。

---

eia_dataframe_describe _tool

• name を省略すると、アクティブなステージング済みデータフレームが一覧表示されます。ハンドルを渡すと、その内容を確認できます。見つからない場合は、found: false と active_names が返されます。
• 各項目には、source_tool、query_params、created_at、expires_at、row_count、truncated／max_rows、column_schema が含まれます。一覧表示によって有効期限が延長されることはありません。

---

eia_dataframe_query _tool

• ステージング済みハンドルに対して、読み取り専用の SQL SELECT を 1 つ実行します。row_limit のデフォルトは 1000 です。preview はインライン表示する範囲を絞り込み、0 を指定できます。どちらの入力でも 10000 を超える整数は 10000 に制限され、要求値と実効値が通知に表示されます。各表示面の 64,000 バイトの上限により、行数がさらに少なくなる場合があります。register_as は完全な結果を引き続きステージングします。
• truncated: true は、totalRows が上限値であり、全件数ではないことを意味します。register_as は、未使用の名前で完全な結果を正確な件数とともにステージングします。残りをページ取得するための ORDER BY … LIMIT/OFFSET クエリが通知に示されます。
• 算術演算には EIA の VARCHAR 値をキャストしてください。書き込み、ファイル読み取り、システムカタログへのアクセスは拒否されます。宣言されている失敗には、missing_table、invalid_sql、non_select_statement、denied_function、multi_statement、sql_read_only、system_catalog_access、register_as_clash が含まれます。

---

eia_dataframe_drop _tool

• ステージング済みデータフレームを削除するには name を渡します。EIA_DATAFRAME_DROP_ENABLED=true が必要です。
• 一致するものがない場合は dropped: false が返されます。削除に失敗すると、再試行可能な canvas_drop_failed が返され、データフレームはステージングされたままになります。クリーンアップは任意です。データフレームは 24 時間未使用でいると期限切れになります。

特長

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、切り替え可能な認証（none / jwt / oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースに対応した構造化ログを備えています。

EIA 固有の機能：

• EIA API v2 のトップレベルデータセットカテゴリ全14種に対応し、ルートツリーをプロセス内にキャッシュします
• ルート名・説明、STEO と SEDS の全1,469件および968件の系列名、ファセット値を対象にあいまい検索（Fuse.js）を行います。ウォームアップ時に、ベンチマーク対象の石油・天然ガス系列名1,753件と、その中のRTO需給調整機関をインデックス化します
• ファセット値は eia_describe_route によってルートごとに取得・キャッシュされます。EIA が返さない一覧は unavailable_facets で報告され、次回の呼び出し時に再試行されます
• メタデータを取得できなかったルートは、除外されずに eia_search_routes を通じて報告されます
• DataCanvas（DuckDB）はデフォルトで有効で、ステージングは呼び出しごとにオプトインします。キャンバスが無効の場合、3つのデータフレームツールは呼び出せません

エージェントに適した出力：

• 出典情報 — eia_query_route は正規ルートを返し、ステージングされたデータフレームには source_tool と query_params が記録されます
• 上限付きウィンドウの通知 — 応答が切り詰められた場合、上限に対する件数と、次の呼び出しを示す notice が返されます
• 型付きエラー — エラーの reason の値（例：route_not_queryable、invalid_facet、missing_table）には、復旧のヒントである recovery が含まれます

はじめに

公開ホストインスタンス

https://eia-energy.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントを接続してください：

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

セルフホスト／ローカル

api.eia.gov で無料の API キーを取得し、MCP クライアントの設定ファイルに以下を追加してください。

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

または npx を使用します（Bun は不要です）：

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

または 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"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください：

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

前提条件

• Bun v1.4.0 以降（または Node.js v24+）。
• api.eia.gov で取得できる無料の EIA API キー。DEMO_KEY はすぐにレート制限に達するため、継続的に利用するには実際のキーが必要です。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd eia-energy-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

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

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマで検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
EIA_API_KEY	必須です。 api.eia.gov で取得できる無料の API キーです。すべてのリクエストで api_key として付加されます。	—
EIA_BASE_URL	EIA API のベース URL です。	https://api.eia.gov/v2
EIA_DATASET_TTL_SECONDS	データフレームの有効期間（秒）です。データフレームを参照する各 eia_dataframe_query によって延長されます。	86400（24 時間）
EIA_DATAFRAME_DROP_ENABLED	true に設定すると、eia_dataframe_drop が利用可能になります（CANVAS_PROVIDER_TYPE=none の場合は効果がありません）。キャンバスを誤ってクリーンアップしないよう、デフォルトでは無効です。	false
EIA_CANVAS_MAX_ROWS	eia_query_route のステージングにおける行数の上限です。この上限に達すると、リクエストがさらに 5 回必要になります。electricity/retail-sales のような幅の狭いルートでは約 8.5 秒、electricity/facility-fuel のような幅の広いルートでは 30～46 秒かかります。呼び出しの期限を超えるステージングは早期に停止し、再開するオフセットを示します。	25000
EIA_FACET_VALUE_CAP	切り詰める前に eia_describe_route がファセットごとに返すファセット値の上限です。facet と values_offset を使ってページングするか、values_query で絞り込んでください。	50
CANVAS_PROVIDER_TYPE	DataCanvas プロバイダーです。duckdb を指定すると、eia_dataframe_describe、eia_dataframe_query、stage: true が有効になります。削除には EIA_DATAFRAME_DROP_ENABLED=true も必要です。none を指定すると DataCanvas は無効になります。Claude Desktop バンドルでは none が設定されます。	duckdb
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパスです。	/mcp
MCP_SESSION_MODE	HTTP セッションのモードです。stateless、stateful、または auto を指定します。	stateless
MCP_PUBLIC_URL	TLS を終端するリバースプロキシ環境で使用する、公開オリジンの上書き設定です。	—
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（RFC 5424）。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。in-memory、filesystem、supabase、cloudflare-kv/r2/d1 を指定します。	in-memory
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false

省略可能な上書き設定の一覧は、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行する：

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

• チェックとテストを実行する：

  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

Dockerfile では、HTTP トランスポートとステートレスセッションモードがデフォルトで設定され、ログは /var/log/eia-energy-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツールの定義（*.tool.ts）です。参照、説明、検索、クエリ、および 3 つの DataCanvas データフレームツールが含まれます。
src/services/eia	EIA API v2 サービスです。ルートツリーのキャッシュ、Fuse.js インデックス、ファセットの並列取得、HTTP クライアントを提供します。
src/services/canvas-bridge	DataCanvas ブリッジです。EIA クエリの結果を DuckDB データフレームとして登録し、SQL クエリを振り分けます。
tests/	src/ に対応する単体テストと統合テストです。
docs/	設計ドキュメント（design.md、idea.md）です。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用してください。
• eia_query_route の前に必ず eia_describe_route を呼び出してください。ファセット値の取得には個別の API 呼び出しが必要で、ルートのメタデータには含まれません。
• EIA のレスポンスをラップする際は、未加工のデータを検証し、ドメイン型に正規化してから出力スキーマに従って返してください。データ値は文字列です。暗黙的に型変換しないでください。

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。