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

• Historical Pool Price and System Marginal Price retrieval with explicit units and timezones

• Deterministic analytics: period comparison, price-event detection, condition evidence

• GridStatus-backed AESO adapters plus a direct APIM httpx client for contracts (not a full second production stack)

• Query bounds, caching, retries, and secret-safe error handling

• Resources for glossary, dataset catalog, and methodology notes

Implemented datasets

Analytics: compare_market_periods, find_price_events, explain_market_conditions, compare_forecast_to_actual.

Architecture

MCP clients
    |
    v
FastMCP adapter (aeso_mcp/mcp)
    |
    v
Domain services (market, grid, assets, analytics)
    |
    +------------------+
    |                  |
    v                  v
GridStatus provider    Direct AESO APIM (httpx)
    |                  |
    +---------+--------+
              |
              v
          AESO APIs

Domain code does not depend on FastMCP. Framework changes should stay in aeso_mcp/mcp/.

Requirements

• Python 3.13+

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

• uv recommended

Installation

See LIMITATIONS.md for an honest gap inventory. PyPI publication is deferred until after human review.

From GitHub (current)

Until the package is published to PyPI:

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

Or install editable for 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

From PyPI (deferred)

Not published yet. After review and an intentional publish, install with:

export AESO_API_KEY=your-key
uvx 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": ["--from", "git+https://github.com/bchoi-qwe/aeso-mcp.git", "aeso-mcp"],
      "env": {
        "AESO_API_KEY": "your-key"
      }
    }
  }
}

HTTP transport

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

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

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.

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

• Human review against LIMITATIONS.md before any PyPI / MCP Registry publish

• Merit order, metered volumes, and unit commitments when reliable sources exist

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