AESO MCP

aeso-mcp

Albertaの電力市場に関する、エージェントネイティブで強い型付けを備えた、公式AESOデータへのアクセスと分析。

独立したオープンソースプロジェクトです。Alberta Electric System Operator（AESO）と提携しておらず、同機関からの承認も受けていません。

概要

aeso-mcp は、Albertaの電力市場に関する観測データと決定論的分析をAIクライアントに提供するModel Context Protocol（MCP）サーバーです。信頼性の高い構造化AESOデータを必要とするエネルギーアナリスト、研究者、開発者、ジャーナリスト、市場参加者、AIエージェント向けに設計されており、単なるRESTの薄いデコレーター層ではありません。

特長

• Pydanticの入力／出力と構造化された結果を備えた、型付きMCPツール
• MCP 2026-07-28を対象とした安定版FastMCP 4.0.10ランタイム。FastMCPの接続ごとのネゴシエーションにより、旧式のセッションベースのクライアントにも対応
• 価格、負荷、発電、連系線潮流、予備力を統合した最新市場スナップショット
• Pool Price、System Marginal Price、負荷、発電のページネーション対応履歴取得
• 公式の個別発電設備別Historical CSD Generation Dataを、1時間および5分単位で提供
• 再現可能な調査向けの、任意の増分DuckDBインデックスとパーティション分割されたParquetスナップショット
• 公式のAIL、Pool Price、風力、太陽光、および風力／太陽光統合予測の公開情報を、単一の型付きget_forecastコントラクトで提供。公開時点の記録を保持し、公開時系列が不明なデータを除外するポイントインタイムのas_of選択にも対応
• 公式の供給充足度、供給余剰、FFR Net Schedule、Dispatch Down Service、TMR参照価格、AIESシステムイベントのレポート
• 公式の過去の充足度／余裕量ウェブコード、送電停止、計画エリア別の1時間単位の負荷／発電、制約量、EEAイベント、運転予備力指令、および最新のPool Participantレジストリを、単一の型付き調査アーカイブコントラクトで提供
• 認証が必要なAPIMレポート。メリットオーダー、コミットメント、発電能力／停止、連系線、計量済み電力量、運転予備力のオファー制御に対応
• 決定論的分析：簡潔な履歴要約、期間比較、イベント検出、条件の証拠、価格分布、実現価格、純負荷、供給スタック、発電、停止との関連分析、汎用的な予測精度、発電設備の総エネルギー収益、CSDと計量済みデータの比較、変化率、供給余剰との関連分析、透明性の高い供給逼迫指標に加え、参加者集中度、地域別分析、制約量、需給逼迫、システム周波数の簡潔な分析
• 決定論的な調査マニフェストにより、複数の情報源を用いた市場イベント分析の正確な入力公開情報、パラメーター、方法論、完全性、性能低下に関する警告を特定
• 公開されている運転予備力の稼働時／待機時価格、7日間予測、発動、要約
• サーバーパッケージと起動方法を一つに統合。AESO_API_KEYは常に必須であり、認証情報なしの縮小版サーバーモードはありません
• クエリ範囲、キャッシュの出所、完全性メタデータ、上流のRetry-After処理、秘密情報を含まない機械可読エラー
• Host／Origin検証、ベアラー認証（デフォルトでループバック以外へのバインド時に必須）、レート／同時実行数制限、リクエストサイズ上限、プローブ、相関IDを備えた強化済みHTTPトランスポート
• 再利用可能なMCPプロンプトに加え、用語集、機能、データセット、方法論の各リソース

実装済みデータセット

データセット	ツール	備考
市場スナップショット	get_market_snapshot	現在の統合ビュー
プール価格	get_pool_prices	CAD/MWh、1時間単位
システム限界価格	get_system_marginal_prices	CAD/MWh、1分単位
アルバータ州内部負荷	get_load	MW、予測は任意
発電量／燃料構成	get_generation	全燃料の現在値、風力／太陽光の履歴
連系線潮流	get_interchange	現在の経路別潮流、MW
運転予備力	get_reserves	現在のMW指標
発電機停止	get_outages	燃料／技術別の1時間ごとの停止容量
AIES の容量／停止	get_generation_capacity	1時間ごとのMC、AC、運転中、および休止停止のMW
負荷停止予測	get_load_outage_forecast	1時間ごとの予測MW
エネルギー merit order	get_energy_merit_order	過去のブロック、公開まで60日の遅延
ユニットコミットメント	get_unit_commitments	発電ユニットのコミットメント指令
連系線容量	get_intertie_capability	輸入／輸出ATC、TTC、マージン、総オファー
連系線容量の停止	get_intertie_outages	連系線／フローゲートに影響する停止
計量済み電力量	get_metered_volumes	資産別の1時間ごとのMWh、IDによる絞り込みは任意
OR オファー制御	get_operating_reserve_offer_control	過去の予備力オファーブロック、60日の遅延
承認済み送電停止	get_approved_transmission_outages	AESO が承認した計画送電停止
長期送電停止	get_long_range_transmission_outages	暫定的な約24か月先までの重要な停止
MCSINR	get_monthly_cumulative_net_revenue	オファー上限の発動基準に対する累積純収益
二次オファー上限	get_secondary_offer_price_limit	二次オファー上限が適用中かどうか
資産	get_assets	フィルター付きの登録簿
CSD の過去の発電量	get_historical_generation	個別資産、運用MWを1時間／5分単位で表示
公式予測	get_forecast	AIL／プール価格／風力／太陽光。期間と間隔はデータソースごとに異なる
公式調査アーカイブ	get_research_data	過去の需給余力／供給余力、送電、計画エリア、制約、EEA、OR 指令、および現在の参加者記録
供給充足度／供給余力	get_supply_adequacy	公式の1時間ごとのカテゴリ別ステータス区分
供給余剰	get_supply_surplus	公式の1時間ごとのゼロ価格予測ステータス
FFR ネットスケジュール	get_ffr_net_schedule	1時間ごとの計画輸入（負）／輸出（正）、MW
ディスパッチ・ダウン・サービス	get_dispatch_down_service	公開済みDDS供給可能量、MW
TMR 参照価格	get_tmr_reference_price	適用日別の公開済み価格、CAD/MWh
AIES システムイベント	get_system_events	範囲指定可能なイベントログのコメント。イベント終了時刻の推定なし
UC 清算概要	get_uc_settlement_summary	1時間ごとの金額（CAD）と課金対象MW
OR 価格	get_operating_reserve_prices	アクティブ／スタンバイの価格構成要素と取引量
OR 予測	get_operating_reserve_forecast	現在から7日間の1時間ごとのMW予測
OR 発動	get_operating_reserve_activations	1時間ごとのスタンバイ取引量と発動価格

分析：summarize_market_history、assess_supply_tightness、compare_market_periods、 find_price_events、explain_market_conditions、compare_forecast_to_actual、 get_price_statistics、get_price_duration_curve、analyze_market_event、 calculate_capture_prices、analyze_net_load、analyze_supply_stack、 analyze_intertie_utilization、analyze_generation_mix、analyze_asset_dispatch、 analyze_outage_impact、analyze_forecast_error、calculate_asset_energy_revenue、 compare_csd_to_metered、analyze_ramps、analyze_supply_surplus_events、 summarize_operating_reserve_market、analyze_participant_concentration、 analyze_regional_load_generation、analyze_constrained_volume、analyze_scarcity、および analyze_system_frequency。

アーキテクチャ

ドキュメントサイトには、包括的なアーキテクチャと MCP Inspector の解説と MCP の相互運用性とセキュリティに関するマトリックスがあります。

MCP clients
    |
    v
FastMCP adapter (aeso_mcp/mcp)
    |
    v
Domain services (market, grid, history, forecasts, reports, research, reserves, operations)
    |
    +---------------+----------------+----------------+----------------+
    |               |                |                |
    v               v                v                v
GridStatus     Direct APIM     Public reports    CSD archive
    |               |           (ets.aeso.ca)      (Box)
    +-------+-------+
            |
            v
      AESO APIM gateway

ドメインコードは FastMCP に依存しません。フレームワークの変更は aeso_mcp/mcp/ 内にとどめてください。 上流のクライアントはすべて、この単一サーバーの実装詳細です。APIM キーは apimgw.aeso.ca にのみ送信され、 許可リストに登録された ETS または Box のホストに送信されることはありません。

要件

• Python 3.13+
• developer-apim.aeso.ca で取得した AESO APIM API キー
• uv を推奨

インストール

ギャップの一覧については、LIMITATIONS.md を参照してください。

PyPI から（推奨）

export AESO_API_KEY=your-key
uvx aeso-mcp

DuckDB／Parquet による履歴データの増分保存を利用する場合：

uvx --from 'aeso-mcp[analytics]' aeso-mcp

GitHub から

現在のリポジトリのバージョンを直接実行する場合：

export AESO_API_KEY=your-key
uvx --from git+https://github.com/bchoi-qwe/aeso-mcp.git aeso-mcp

開発

git clone https://github.com/bchoi-qwe/aeso-mcp.git
cd aeso-mcp
uv sync --group dev
cp .env.example .env   # set AESO_API_KEY
uv run aeso-mcp

Docker

docker build -t aeso-mcp .
docker run --rm \
  -e AESO_API_KEY=your-key \
  -e AESO_MCP_HTTP_BEARER_TOKEN=replace-with-a-long-random-token \
  -p 8000:8000 \
  aeso-mcp

MCP クライアントの Authorization: Bearer ... ヘッダーに同じトークンを指定してください。イメージは 0.0.0.0 にバインドされるため、デフォルトでベアラー認証が必須です。組み込みの HTTP リスナーは TLS を終端しません。ホスト外からのトラフィックでは、信頼できるリバースプロキシで TLS を終端し、 ベアラー認証情報をパブリックな平文 HTTP 経由で送信しないでください。MCP の相互運用性とセキュリティを参照してください。

AESO API キーの取得

1. AESO 開発者ポータルで登録します
2. AESO のパブリック API 製品をサブスクライブします
3. プライマリ／セカンダリのサブスクリプションキーをコピーします
4. 環境に AESO_API_KEY を設定します（決してコミットしないでください）

認証情報がない場合は、対処方法を示す起動エラーが表示されます。このキーが MCP ツールを通じて返されたり、ログに記録されたりすることはありません。

MCP クライアント設定の例

ドキュメントサイトのMCP クライアント設定では、Codex、ChatGPT デスクトップアプリ、Claude Desktop、Claude Code、Cursor 用に整備された設定手順を確認できます。

Cursor／Claude Desktop 形式（stdio）

{
  "mcpServers": {
    "aeso": {
      "command": "uvx",
      "args": ["aeso-mcp"],
      "env": {
        "AESO_API_KEY": "your-key"
      }
    }
  }
}

HTTP トランスポート

uv run aeso-mcp --transport http --host 127.0.0.1 --port 8000

HTTP では常に Host と Origin が検証されます。ループバック以外のアドレスへのバインドでは、 AESO_MCP_HTTP_BEARER_TOKEN が設定されていない場合、起動が拒否されます。組み込みリスナーは 平文 HTTP を使用します。信頼できるプライベートネットワークの外部に公開する前に、信頼できる イングレスで TLS を終端してください。リスクを許容する隔離環境向けに、 明示的な AESO_MCP_HTTP_ALLOW_INSECURE_REMOTE=true のオーバーライドもありますが、 デフォルトでは有効になりません。デプロイ時には AESO_MCP_HTTP_ALLOWED_HOSTS と AESO_MCP_HTTP_ALLOWED_ORIGINS も設定してください。/healthz と /readyz に市場データや シークレットが含まれることはありません。実行時の各種制限付き設定については .env.example を参照してください。

プロンプトの例

• アルバータ州の現在の電力系統の状況はどうなっていますか？
• 現在のプール価格はいくらですか？
• 過去 24 時間のアルバータ州のプール価格を表示してください。
• 今日のプール価格を昨日の価格と比較してください。
• 今週、価格が最も高かった時間帯はいつですか？
• 現在、風力と太陽光はそれぞれどれくらい発電していますか？
• 今週、最も大きな価格急騰の際に何が起きましたか？
• その事象の間、7 日間の風力発電予測はどれくらい不正確でしたか？
• その時、AESO は供給余剰または供給余力の逼迫を示すステータスを発表していましたか？
• この資産の計量済み MWh による総 Pool Price エネルギー収益はいくらですか？
• 今日の価格上昇に関連する根拠を説明してください。

ツール

ツール	目的
get_market_snapshot	現在の市場概要
get_pool_prices	時間単位の Pool Price 履歴
get_system_marginal_prices	分単位の SMP 履歴
get_load	Alberta Internal Load
get_generation	燃料構成／再生可能エネルギーの履歴
get_interchange	連系線の潮流
get_reserves	運転予備力の指標
get_outages	燃料別の発電機停止容量（時間単位）
get_generation_capacity	燃料別の AIES 設備能力と停止状況のグループ化
get_load_outage_forecast	負荷・停止予測（時間単位）
get_energy_merit_order	エネルギーのメリットオーダー・ブロック履歴
get_unit_commitments	発電ユニットの起動指令
get_intertie_capability	連系線／フローゲートの ATC、TTC、マージン
get_intertie_outages	連系線の能力に影響する停止
get_metered_volumes	資産別の計量エネルギー
get_operating_reserve_offer_control	予備力オファー制御ブロックの履歴
get_approved_transmission_outages	承認済みの計画送電停止
get_long_range_transmission_outages	暫定的な長期送電停止
get_assets	資産レジストリ
get_monthly_cumulative_net_revenue	現在の MCSINR 公表データ
get_secondary_offer_price_limit	現在のセカンダリーオファー上限価格の状況
compare_market_periods	期間ごとの集計比較
find_price_events	高価格イベントの検出
explain_market_conditions	構造化された根拠（因果関係を説明する文章ではありません）
compare_forecast_to_actual	AIL 予測と実績の精度
summarize_market_history	価格と負荷に関する時間／日／週／月単位の簡潔な要約
assess_supply_tightness	予備力で調整した供給マージンの透明性の高いスクリーニング
get_historical_generation	公式の個別資産 CSD アーカイブ履歴
sync_historical_store	DuckDB／Parquet へのローカル増分取り込み
get_historical_store_status	ローカルの対象範囲、マニフェスト、パーティションの状況
get_forecast	公式の AIL、Pool Price、風力、太陽光、風力／太陽光合算の予測
get_research_data	検証済みの公式な履歴／空間／信頼性アーカイブのいずれかから取得する、範囲を限定したページ
get_supply_adequacy	公式な供給充足度と市場供給クッションのステータス帯
get_supply_surplus	公式の時間単位の供給余剰予測状況
get_ffr_net_schedule	スケジュールされた FFR 連系線送電量の履歴
get_dispatch_down_service	ディスパッチダウンサービスの利用可能性レポート
get_tmr_reference_price	公表済み TMR 参照価格
get_system_events	範囲を限定した AIES イベントログのメッセージ
get_uc_settlement_summary	UC 金額と請求対象量の公開時間別データ
get_price_statistics	価格分布とボラティリティの統計
get_price_duration_curve	Pool Price の超過曲線
analyze_market_event	対象期間と基準期間における複数系列の関連性
calculate_capture_prices	発電量で加重した価格と捕捉率
analyze_net_load	AIL から選択した再生可能エネルギー発電量を差し引いた値
analyze_supply_stack	過去のオファースタック分析
analyze_intertie_utilization	総オファー量から設備能力を推定するプロキシ
analyze_generation_mix	CSD による燃料別エネルギーとシェア
analyze_asset_dispatch	資産の出力、設備利用率、出力変化
analyze_outage_impact	時間単位の停止と価格の関連性
analyze_forecast_error	一般的な予測誤差、パーセンタイル、市場時間別・リードタイム別プロファイル
calculate_asset_energy_revenue	計量 MWh × Pool Price による総エネルギー収益
compare_csd_to_metered	運用上の CSD 出力と計量 MWh の比較
analyze_ramps	時間間隔を考慮した AIL、ネット負荷、再生可能エネルギー、または資産の出力変化
analyze_supply_surplus_events	明示的な供給余剰状態における価格／負荷／再生可能エネルギーの関連性
get_operating_reserve_prices	アクティブ／スタンバイの価格構成要素と取引量
get_operating_reserve_forecast	7 日間の予備力取引量予測
get_operating_reserve_activations	時間単位のスタンバイ発動
summarize_operating_reserve_market	商品の価格／取引量／発動状況の要約
analyze_participant_concentration	現在の参加者マッピングを使用したオファー量シェアと HHI
analyze_regional_load_generation	計画地域別および地域別の負荷／発電集計
analyze_constrained_volume	計画地域／燃料別の制約対象 MWh と、任意の価格関連性
analyze_scarcity	過去の充足度／クッションのウェブコード、EEA、価格状況
analyze_system_frequency	10 秒間隔の周波数統計を 6 時間分簡潔に表示。生の行データは出力しません
市場および調査ツールは読み取り専用です。sync_historical_store は、設定されたローカルの履歴ストアルートにのみ書き込みます。AESO やその他の外部システムを変更することはありません。

リソース

URI	内容
aeso://glossary	市場用語
aeso://datasets	データセットカタログ
aeso://methodology/pool-price	Pool Price の解釈
aeso://methodology/system-marginal-price	SMP の解釈
aeso://capabilities	ツール、プロンプト、リソースの全一覧
aeso://methodology/{dataset}	データセット固有の解釈と注意事項

プロンプト：daily_market_brief、investigate_price_event、compare_market_days。

データの意味

• タイムゾーン：America/Edmonton（AESO 市場時間）。夏時間の切り替え日は、現地時間で 23 時間または 25 時間になる場合があります。
• 時間間隔：明示的な interval_start / interval_end（リクエストでは半開区間を使用します）。
• 単位：Pool Price / SMP → CAD/MWh、負荷 / 発電 / 電力融通 / 予備力 → MW。
• ステータス：メタデータには actual / forecast などが含まれます。予測値が確定済みの実績値として扱われることはありません。
• 確定性：運用フィードは暫定版の場合があります。最終精算済みであると想定しないでください。
• 特定時点の予測：as_of は、発行・公開時刻と取得時刻が境界以前と判明しているバージョンのみを選択します。時系列が不明なデータは除外されます。永続化された履歴に存在しない対象時間帯は、後日の公開データで補完されず、未観測のままになります。
• 完全性：ソースの更新頻度が判明している場合、メタデータには利用可能な系列と欠落している系列、および予想される観測値と欠落している観測値が報告されます。任意の拡充処理に失敗した場合は、警告とともに部分的または劣化した結果として通知されます。
• ページネーション：価格、SMP、負荷、発電、運用レポートの生データは、next_offset を含む page メタデータを返します。長い生データ系列を取得する前に、summarize_market_history を使用してください。
• キャッシュのタイミング：retrieved_at は上流からの取得時刻を示します。served_at、cache_hit、cache_age は、レスポンスがいつ、どのように返されたかを示します。
• 調査の識別情報：analyze_market_event.analysis_manifest には、正確なソース、パラメーター、方法論のバージョン、警告、および決定論的な SHA-256 の analysis_id が記録されます。

開発

uv sync --group dev
uv run ruff check src tests scripts
uv run pyright src
uv run pytest tests/unit tests/contract tests/mcp tests/evals --cov=aeso_mcp
uv run python scripts/generate_catalog.py --check
uv run mkdocs build --strict
uv build

任意のライブテスト：

AESO_API_KEY=... uv run pytest tests/integration -m integration

MCP Inspector：

# Prefer the console entrypoint; or point Inspector at:
# uv run aeso-mcp
npx @modelcontextprotocol/inspector uv run aeso-mcp

テスト

• tests/unit — 時刻、境界、分析、設定
• tests/contract — respx を使用した AESO APIM フィクスチャ
• tests/mcp — ツール／リソースの検出と構造化出力
• tests/integration — オプトイン方式の AESO ライブ呼び出し

セキュリティ

SECURITY.md を参照してください。主な対策：任意の URL／シェル／SQL ツールを使用しないこと、ホストの許可リスト、シークレットの適切な管理、クエリの制限、stdio での stderr ロギング。

開発状況

バージョン 0.4.0 には、履歴ストア、完全な CSD 発電アダプター、公式の予測／レポートプロバイダー、汎用調査分析、運用予備力市場のインターフェース、評価スイート、ドキュメントサイトが含まれています。また、特定時点の予測バージョン、再現性マニフェスト、リリースポリシーの強化、検証済みの公式調査データアーカイブも含まれています。

貢献

CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

免責事項

このプロジェクトは、公開されている AESO API への独立したオープンソースインターフェースです。AESO の公式製品ではなく、AESO と提携しておらず、AESO による推奨も受けていません。市場データは暫定版または不完全な場合があります。重要な意思決定については、AESO の公式公開情報で確認してください。