aeso-mcp

Agent-native, strongly typed access and analytics for Alberta's electricity market using official AESO data.

Independent open-source project. Not affiliated with or endorsed by the Alberta Electric System Operator (AESO).

What it is

aeso-mcp is a Model Context Protocol (MCP) server that exposes Alberta electricity-market observations and deterministic analytics to AI clients. It is designed for energy analysts, researchers, developers, journalists, market participants, and AI agents that need reliable, structured AESO data—not a thin REST decorator layer.

Related MCP server: EnergyAtIt MCP Server

Features

• Typed MCP tools with Pydantic inputs/outputs and structured results

• Current market snapshot combining price, load, generation, interchange, and reserves

• Paginated historical Pool Price, System Marginal Price, load, and generation retrieval

• Official individual-asset Historical CSD Generation Data at hourly and five-minute resolution

• Optional incremental DuckDB index and partitioned Parquet snapshots for repeatable research

• Official AIL, Pool Price, wind, solar, and combined wind/solar forecast publications through one typed get_forecast contract, with persisted publication vintages and point-in-time as_of selection that excludes unknown publication chronology

• Official supply-adequacy, supply-surplus, FFR Net Schedule, Dispatch Down Service, TMR reference-price, and AIES system-event reports

• Official historical adequacy/cushion web codes, transmission outages, planning-area hourly load/generation, constrained volume, EEA events, operating-reserve directives, and the current Pool Participant registry through one typed research-archive contract

• Authenticated APIM reports for merit order, commitments, capability/outages, interties, metered volumes, and operating-reserve offer control

• Deterministic analytics: compact history summaries, period comparison, event detection, condition evidence, price distributions, capture price, net load, supply stack, generation, outage association, generalized forecast accuracy, asset gross energy revenue, CSD-versus- metered comparisons, ramps, supply-surplus associations, and transparent supply-tightness indicators, plus participant concentration, regional, constrained-volume, scarcity, and compact system-frequency analysis

• Deterministic research manifests identify exact input publications, parameters, methodology, completeness, and degradation warnings for multi-source market-event analysis

• Public operating-reserve active/standby prices, seven-day forecasts, activations, and summaries

• One complete server package and startup path: AESO_API_KEY is always required; there is no reduced credential-free server mode

• Query bounds, cache provenance, completeness metadata, upstream Retry-After handling, and secret-safe machine-readable errors

• Hardened HTTP transport with Host/Origin validation, bearer authentication required for non-loopback binds by default, rate/concurrency limits, request-size bounds, probes, and correlation IDs

• Reusable MCP prompts plus glossary, capability, dataset, and methodology resources

Implemented datasets

Analytics: 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, and analyze_system_frequency.

Architecture

The documentation site includes a full architecture and MCP Inspector walkthrough.

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

Domain code does not depend on FastMCP. Framework changes should stay in aeso_mcp/mcp/. All upstream clients are implementation details of this single server: the APIM key is sent only to apimgw.aeso.ca and is never sent to the allow-listed ETS or Box hosts.

Requirements

• Python 3.13+

• AESO APIM API key from developer-apim.aeso.ca

• uv recommended

Installation

See LIMITATIONS.md for an honest gap inventory.

From PyPI (recommended)

export AESO_API_KEY=your-key
uvx aeso-mcp

For incremental DuckDB/Parquet historical storage:

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

From GitHub

To run the current repository version directly:

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

Development

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

Send the same token in the MCP client's Authorization: Bearer ... header. The image binds to 0.0.0.0, so it intentionally requires bearer authentication by default.

Obtaining an AESO API key

1. Register at the AESO developer portal

2. Subscribe to the AESO public API product

3. Copy the primary/secondary subscription key

4. Set AESO_API_KEY in your environment (never commit it)

Missing credentials produce an actionable startup error. The key is never returned through MCP tools or logged.

Example MCP client configuration

See the documentation site's MCP client configurations for maintained Codex, ChatGPT desktop app, Claude Desktop, Claude Code, and Cursor setup instructions.

Cursor / Claude Desktop style (stdio)

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

HTTP transport

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

HTTP always validates Host and Origin. A non-loopback bind now refuses to start unless AESO_MCP_HTTP_BEARER_TOKEN is configured. An explicit AESO_MCP_HTTP_ALLOW_INSECURE_REMOTE=true override exists for isolated environments that accept the risk; it is never the default. Also set AESO_MCP_HTTP_ALLOWED_HOSTS and AESO_MCP_HTTP_ALLOWED_ORIGINS for the deployment. /healthz and /readyz contain no market data or secrets. See .env.example for all bounded runtime settings.

Example prompts

• What is Alberta's current grid situation?

• What is the current pool price?

• Show Alberta pool prices over the last 24 hours.

• Compare today's pool prices with yesterday's.

• Which hours had the highest prices this week?

• How much wind and solar are producing right now?

• What happened during the largest price spike this week?

• How inaccurate was the seven-day wind forecast during that event?

• Was AESO publishing a supply-surplus or tight supply-cushion status at the time?

• What gross Pool Price energy revenue did this asset's metered MWh earn?

• Explain the evidence associated with today's price increase.

Tools

Market and research tools are read-only. sync_historical_store writes only to the configured local historical-store root; it does not mutate AESO or another external system.

Resources

Prompts: daily_market_brief, investigate_price_event, and compare_market_days.

Data semantics

• Timezone: America/Edmonton (AESO market time). DST days may have 23 or 25 local hours.

• Intervals: Explicit interval_start / interval_end (half-open ranges in requests).

• Units: Pool Price / SMP → CAD/MWh; load / generation / interchange / reserves → MW.

• Status: Metadata includes actual / forecast / etc. Forecasts are never implied to be settled actuals.

• Finality: Operational feeds may be preliminary; do not assume final settlement.

• Point-in-time forecasts: as_of selects only vintages with known issue/publication times at or before the boundary. Unknown chronology is excluded; target intervals absent from persisted history remain unobserved rather than being backfilled from a later publication.

• Completeness: Metadata reports available/missing series and expected/missing observations where the source cadence is known. Optional enrichment failures are surfaced as partial or degraded results with warnings.

• Pagination: Raw price, SMP, load, generation, and operational reports return page metadata with next_offset. Use summarize_market_history before retrieving long raw series.

• Cache timing: retrieved_at identifies the upstream fetch; served_at, cache_hit, and cache_age identify when and how the response was served.

• Research identity: analyze_market_event.analysis_manifest records exact sources, parameters, methodology version, warnings, and a deterministic SHA-256 analysis_id.

Development

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

Optional live tests:

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

• tests/unit — time, bounds, analytics, config

• tests/contract — AESO APIM fixtures via respx

• tests/mcp — tool/resource discovery and structured outputs

• tests/integration — opt-in live AESO calls

Security

See SECURITY.md. Highlights: no arbitrary URL/shell/SQL tools, host allow-list, secret hygiene, bounded queries, stderr logging for stdio.

Development status

Version 0.3.0 includes the historical store, full CSD generation adapter, official forecast/report providers, general research analytics, operating-reserve market surface, eval suite, and documentation site. Unreleased work adds point-in-time forecast vintages, reproducibility manifests, release-policy hardening, and the verified official research-data archive.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Disclaimer

This project is an independent open-source interface to publicly documented AESO APIs. It is not an official AESO product and is not affiliated with or endorsed by AESO. Market data may be preliminary or incomplete; verify critical decisions against official AESO publications.