AESO MCP

aeso-mcp

基于 AESO 官方数据，为阿尔伯塔省电力市场提供面向 Agent、强类型的数据访问与分析。

独立开源项目。与 Alberta Electric System Operator（AESO）无关联，也未获其认可。

项目简介

aeso-mcp 是一个 Model Context Protocol（MCP）服务，可向 AI 客户端提供阿尔伯塔省电力市场观测数据和确定性分析。它面向需要可靠、结构化 AESO 数据的能源分析师、研究人员、开发者、记者、市场参与者和 AI Agent，而非简单的 REST 装饰层。

功能特性

• 带有 Pydantic 输入／输出和结构化结果的强类型 MCP 工具
• 稳定的 FastMCP 4.0.10 运行时，面向 MCP 2026-07-28，并通过 FastMCP 的逐连接协商支持基于旧版会话的客户端
• 汇总价格、负荷、发电量、互联交换和备用容量的当前市场快照
• 分页获取历史 Pool Price、System Marginal Price、负荷和发电量数据
• 官方单个资产的 Historical CSD Generation Data，支持小时和五分钟分辨率
• 可选的增量 DuckDB 索引和分区 Parquet 快照，支持可重复研究
• 通过统一的强类型 get_forecast 契约提供官方 AIL、Pool Price、风能、太阳能以及风能／太阳能综合预测发布数据，并持久化发布版本，支持按时间点选择 as_of，且会排除发布时间顺序未知的数据
• 官方供给充足性、供给盈余、FFR Net Schedule、Dispatch Down Service、TMR 参考价格和 AIES 系统事件报告
• 通过统一的强类型研究档案契约，提供官方历史 adequacy/cushion 网络代码、输电停运、规划区小时负荷／发电量、受限电量、EEA 事件、运行备用指令，以及当前 Pool Participant 注册表
• 经过身份验证的 APIM 报告，涵盖 merit order、承诺、能力／停运、互联线、计量电量和运行备用报价控制
• 确定性分析：精简历史摘要、时段对比、事件检测、状况证据、价格分布、捕获价格、净负荷、供给曲线、发电量、停运关联、通用预测准确度、资产总能源收入、CSD 与计量数据对比、爬坡、供给盈余关联、透明的供给紧张度指标，以及参与者集中度、区域、受限电量、稀缺性和精简系统频率分析
• 确定性研究清单会标明多源市场事件分析所用的准确输入发布数据、参数、方法、完整性和降级警告
• 公开的运行备用实时／备用价格、七日预测、激活情况和摘要
• 完整统一的服务软件包和启动路径：始终需要 AESO_API_KEY；不提供免凭据的精简服务模式
• 查询范围、缓存来源、完整性元数据、上游 Retry-After 处理，以及安全保护机密的机器可读错误
• 加固的 HTTP 传输，包含 Host／Origin 验证、非环回绑定默认要求的 bearer 身份验证、速率／并发限制、请求大小限制、探针和关联 ID
• 可重复使用的 MCP 提示词，以及术语表、能力、数据集和方法资源

已实现的数据集

数据集	工具	备注
市场快照	get_market_snapshot	当前综合视图
Pool Price	get_pool_prices	每小时 CAD/MWh
系统边际价格	get_system_marginal_prices	分钟级 CAD/MWh
Alberta 内部负荷	get_load	MW；可选预测
发电量 / 燃料结构	get_generation	当前涵盖所有燃料；历史风能 / 太阳能
互联交换	get_interchange	当前路径潮流 MW
运行备用	get_reserves	当前 MW 指标
发电机停运	get_outages	按燃料 / 技术统计的每小时停运容量
AIES 容量 / 停运	get_generation_capacity	每小时 MC、AC、运行中及封存停运 MW
负荷停运预测	get_load_outage_forecast	每小时预测 MW
能源 Merit Order	get_energy_merit_order	历史区块；发布延迟 60 天
机组承诺	get_unit_commitments	发电机组承诺指令
联络线能力	get_intertie_capability	输入 / 输出 ATC、TTC、裕度、总报价
联络线能力停运	get_intertie_outages	影响联络线 / 潮流门的停运
计量电量	get_metered_volumes	按资产统计每小时 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
官方预测	get_forecast	AIL / Pool Price / 风能 / 太阳能；时段和频率因来源而异
官方研究存档	get_research_data	历史充裕度 / 缓冲、输电、规划区域、约束、EEA、OR 指令及当前参与方记录
供应充裕度 / 缓冲	get_supply_adequacy	官方每小时分类状态区间
供应盈余	get_supply_surplus	官方每小时零价格预测状态
FFR 净计划	get_ffr_net_schedule	每小时计划输入（负值）/ 输出（正值）MW
调度降载服务	get_dispatch_down_service	已发布 DDS 可用 MW
TMR 参考价格	get_tmr_reference_price	按生效日期发布的 CAD/MWh 数值
AIES 系统事件	get_system_events	有界事件日志评论；不推断事件结束时间
UC 结算摘要	get_uc_settlement_summary	每小时 CAD 金额和计费 MW
OR 价格	get_operating_reserve_prices	活跃和待命价格组成及电量
OR 预测	get_operating_reserve_forecast	当前未来七天的每小时 MW 预测
OR 激活	get_operating_reserve_activations	每小时待命电量和激活价格

分析：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，因此默认情况下需要进行 bearer 身份验证。内置 HTTP 监听器 不会终止 TLS；对于来自主机外部的流量，请在可信的反向代理处终止 TLS，切勿通过公共明文 HTTP 发送 bearer 凭据。请参阅 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 小时的阿尔伯塔电力池价格。
• 比较今天和昨天的电力池价格。
• 本周哪些时段价格最高？
• 当前风能和太阳能的发电量是多少？
• 本周最大的价格飙升期间发生了什么？
• 该事件期间，七天风力预测有多不准确？
• 当时 AESO 是否发布了供应盈余或供应缓冲紧张状态？
• 该资产计量的 MWh 带来了多少电力池价格能源总收入？
• 解释与今天价格上涨相关的证据。

工具

工具	用途
get_market_snapshot	当前市场概览
get_pool_prices	每小时 Pool Price 历史数据
get_system_marginal_prices	分钟级 SMP 历史数据
get_load	Alberta 内部负荷
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	精简的 6 小时 10 秒频率统计；不输出原始行
市场和研究工具为只读。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 / shell / SQL 工具、主机允许列表、密钥管理、查询范围限制，以及 stdio 日志写入 stderr。

开发状态

0.4.0 版包含历史数据存储、完整的 CSD 发电适配器、官方预测 / 报告提供方、通用研究分析、运行备用市场接口、评估套件和文档网站。该版本还包含时间点预测版本、可复现性清单、发布策略强化，以及经过验证的官方研究数据归档。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT — 请参阅 LICENSE。

免责声明

本项目是面向 AESO 公开文档所述 API 的独立开源接口。它不是 AESO 官方产品，也未获得 AESO 的认可或背书，且与 AESO 无关联。市场数据可能是初步或不完整数据；重要决策请以 AESO 官方发布内容为准。