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.

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
• 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, forecast accuracy, and transparent supply-tightness indicators
• 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, optional bearer authentication, rate and 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, and compare_forecast_to_actual.

Architecture

MCP clients
    |
    v
FastMCP adapter (aeso_mcp/mcp)
    |
    v
Domain services (market, grid, assets, operations, analytics, transmission, market power)
    |
    +---------------------+------------------------+
    |                     |                        |
    v                     v                        v
GridStatus provider    Direct AESO APIM    Public-reports client
    |                     |                        |
    +----------+----------+                        |
               |                                   |
               v                                   v
       AESO APIM gateway                       ets.aeso.ca

Domain code does not depend on FastMCP. Framework changes should stay in aeso_mcp/mcp/. Both 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.aeso.ca report host.

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

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 -p 8000:8000 aeso-mcp

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

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. For a remotely reachable deployment, explicitly set AESO_MCP_HTTP_ALLOWED_HOSTS and AESO_MCP_HTTP_ALLOWED_ORIGINS; set AESO_MCP_HTTP_BEARER_TOKEN to require bearer authentication. /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?
• Explain the evidence associated with today's price increase.

Tools

All tools are read-only, non-destructive, and network-dependent.

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.
• 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.

Development

uv sync --group dev
uv run ruff check src tests
uv run pyright src
uv run pytest tests/unit tests/contract tests/mcp --cov=aeso_mcp
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.

Roadmap

• Optional DuckDB/Parquet historical analytics store
• Broader forecast vs actual tools

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.