ClariGrid MCP Server

Clarigrid

Unified Python SDK for European and U.S. energy market data.

---

What it is

Clarigrid provides a single, stable Python interface to access and normalise European and U.S. energy market data from multiple sources. All data comes back as timezone-aware pandas DataFrames with consistent column names and units.

Built-in free providers (no API key required) include Energy-Charts (Europe), Energinet (DK1/DK2), SMARD (DE), Elia (BE), NESO (GB), Elexon/BMRS (GB), and ENTSOG (EU gas). Fingrid (FI), GIE AGSI/ALSI (European gas), and TenneT (NL) are also built in and use free API keys. For the United States, CAISO OASIS and NYISO provide no-auth market and system data. EIA-930 provides nationwide hourly balancing-authority load, forecasts, fuel generation, and physical interchange with a free EIA key. Global historical meteorology and solar data are available from NASA POWER without an API key. ENTSO-E and other key-protected sources can be configured as described in API key setup below.

---

Install

pip install clarigrid

For the interactive setup wizard and CLI tools:

pip install clarigrid[auth]

---

Quick start

import clarigrid as cg

# Free providers — no key required.
cg.connect("smard")   # DE prices, load, generation
cg.connect("elia")    # BE load, generation
cg.connect("neso")    # GB load, embedded generation
cg.connect("elexon")  # GB prices, generation mix
cg.connect("entsog")  # EU gas flows (any TSO zone)
cg.connect("energycharts")  # European prices, power, forecasts and flows
cg.connect("energinet")  # DK1/DK2 prices, power, forecasts, flows and CO2
cg.connect("redata")  # ES load, generation, capacity and cross-border flows
cg.connect("rte")  # FR load, generation, forecasts, exchanges and CO2
cg.connect("fingrid")  # FI power, forecasts, flows, balancing and CO2 (free key)
cg.connect("gie")  # European gas storage and LNG inventory (free key)
cg.connect("eia")  # US balancing-authority load, generation and flows (free key)
cg.connect("caiso")  # CAISO day-ahead hub prices (no key)
cg.connect("nyiso")  # NYISO prices, load, forecasts and fuel mix (no key)
cg.connect("nasapower")  # Global daily/hourly weather and solar data (no key)

# Optional: set output timezone (default is UTC).
cg.set_timezone("Europe/Brussels")

# Fetch data — provider is chosen automatically by zone.
prices = cg.get_prices("DE", "2025-01-01", "2025-01-07")  # → smard
load   = cg.get_load("BE",   "2025-01-01", "2025-01-07")  # → elia
gen    = cg.get_generation("GB", "2025-01-01", "2025-01-07")  # → elexon
gas    = cg.get_gas_flows("BE-TSO-0001", "2025-01-01", "2025-01-07")  # → entsog
us_load = cg.get_load("CAISO", "2025-01-01", "2025-01-07")  # → eia (CISO)
np15 = cg.get_prices("CISO_NP15", "2025-01-01", "2025-01-07")  # → caiso
nyc = cg.get_prices("NYISO_NYC", "2025-01-01", "2025-01-07")  # → nyiso
weather = cg.get_weather(
    "40.7128,-74.0060",
    "2025-01-01",
    "2025-01-07",
    source="nasapower",
)

---

API key setup

Some providers (ENTSO-E, TenneT) require a personal API key issued by the upstream data source. Clarigrid supports two ways to supply these keys.

Option 1 — ClarigGrid account (recommended)

Store all your provider keys in one place at clarigrid.energy/saved. The SDK then fetches them automatically using a single ClarigGrid API key.

First-time setup (interactive):

import clarigrid as cg
cg.connect("entsoe")
# Opens browser → log in at clarigrid.energy → keys fetched automatically.

Or use the CLI:

clarigrid setup          # guided wizard for all providers
clarigrid connect entsoe # authenticate a single provider

Headless / CI environments: set one environment variable and no browser is ever needed:

export CLARIGRID_API_KEY=your-clarigrid-uuid

The SDK uses CLARIGRID_API_KEY to fetch all your stored provider keys from clarigrid.energy on the first connect() call of each session.

How to get a CLARIGRID_API_KEY:

1. Log in at clarigrid.energy
2. Add your provider API keys at clarigrid.energy/saved
3. Run cg.connect("entsoe") once in an interactive terminal — the browser flow logs you in and stores your CLARIGRID_API_KEY locally.

---

Option 2 — Manual key entry (no account needed)

If you prefer not to use a clarigrid.energy account, set provider keys directly. Keys are stored in ~/.config/clarigrid/.env (permissions: 600).

Environment variable (recommended for CI):

export ENTSOE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
export TENNET_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Config file — add to ~/.config/clarigrid/.env:

ENTSOE_API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
TENNET_API_KEY="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Zone routing

Each call to cg.connect() registers a provider and its capability-specific zone coverage in an internal router. When you call get_prices("DE"), the router picks the best connected provider for that zone and dataset automatically.

Multiple connect() calls accumulate coverage. If two providers both cover the same zone/dataset pair, the later connect() call wins.

cg.connect("neso")    # covers GB: load, generation
cg.connect("elexon")  # covers GB: prices, generation — overwrites generation slot

# Now: GB prices → elexon, GB load → neso, GB generation → elexon
prices = cg.get_prices("GB", "2025-01-01", "2025-01-02")
load   = cg.get_load("GB",   "2025-01-01", "2025-01-02")

If no connected provider covers the requested zone/dataset, a helpful error is raised:

ZoneNotCoveredError: No connected provider has 'prices' data for zone 'BE'.
  Consider: cg.connect('entsoe')

To bypass routing and force a specific provider:

df = cg.get_load("GB", "2025-01-01", "2025-01-07", source="neso")

---

Output format

All functions return a pandas.DataFrame with:

Price currency is stored in df.attrs["currency"] (for example "EUR", "GBP", or "USD"):

df = cg.get_prices("DE", "2025-01-01", "2025-01-07")
print(df.attrs["currency"])  # 'EUR'

European zone codes follow the ENTSO-E bidding zone convention (BE, DE_LU, FR ...). U.S. electricity uses EIA/NERC balancing-authority codes (CISO, ERCO, PJM, NYIS) and explicit market hubs (CISO_NP15). Common aliases (DE → DE_LU, CAISO → CISO, ERCOT → ERCO) resolve automatically.

---

Timezone

cg.set_timezone("Europe/Brussels")   # all subsequent calls return Brussels time
cg.set_timezone("UTC")               # revert to default

df = cg.get_load("BE", "2025-01-01", "2025-01-07")
# df.index is tz-aware in Europe/Brussels

Data is always fetched and cached as UTC. Timezone conversion is applied at the output boundary only.

---

Caching

Responses are cached locally at ~/.clarigrid/cache/ as Parquet files (requires pip install clarigrid[cache]), keyed by provider + dataset + zone + date range. Historical data is cached indefinitely; live data expires after 1 hour by default.

from clarigrid.core import cache

cache.info()           # DataFrame showing cached entries
cache.clear()          # clear all
cache.clear("smard")   # clear one provider
cache.set_live_ttl(1800)  # change live-data TTL to 30 min

Disable caching per call:

df = cg.get_prices("DE", "2025-01-01", "2025-01-07", use_cache=False)

---

CLI reference

Requires pip install clarigrid[auth].

clarigrid setup                    # guided wizard — configure all providers
clarigrid connect <source>         # authenticate a single provider
clarigrid auth --show              # list configured sources (keys masked)
clarigrid auth --clear <source>    # remove key for a specific source
clarigrid auth --clear --all       # remove all stored keys

---

API reference

All data functions accept:

• source="name" — override the router for this call only
• use_cache=False — bypass the local cache

---

Built-in providers

Keys for entsoe and tennet are issued by the respective upstream provider. Store them via a clarigrid.energy account or set them manually as described in API key setup.

---

Architecture

clarigrid/
├── __init__.py           # public surface: connect, get_prices, set_timezone, …
├── _auth.py              # KeyState machine, auth flows, provider key registry
├── _keystore.py          # ~/.config/clarigrid/.env  read/write (chmod 600)
├── _browser_flow.py      # browser-based OAuth flow (localhost callback server)
├── cli.py                # clarigrid CLI (setup, connect, auth)
├── core/
│   ├── api.py            # top-level functions — routing + normalisation
│   ├── router.py         # ZoneRouter — (zone, capability) → provider
│   ├── session.py        # runtime state: router, connected map, output TZ
│   ├── normalise.py      # canonical column names + unit normalisation
│   ├── registry.py       # register_provider / get_provider
│   ├── interface.py      # DataProvider ABC ← providers implement this
│   ├── cache.py          # filesystem Parquet cache
│   ├── config.py         # legacy key store (~/.clarigrid/keys.toml)
│   ├── exceptions.py     # exception hierarchy
│   └── types.py          # shared constants, zone aliases
├── providers/
│   ├── smard.py          # Bundesnetzagentur SMARD (DE)
│   ├── energycharts.py   # Fraunhofer ISE Energy-Charts (Europe)
│   ├── energinet.py      # Energinet Energi Data Service (DK1/DK2)
│   ├── redata.py         # Red Electrica REData (ES)
│   ├── rte.py            # RTE Eco2mix (FR)
│   ├── elia.py           # Elia Open Data (BE)
│   ├── neso.py           # NESO Data Portal (GB)
│   ├── elexon.py         # Elexon BMRS (GB)
│   ├── eia.py            # EIA-930 balancing-authority operations (US)
│   ├── caiso.py          # CAISO OASIS day-ahead prices (US)
│   ├── nyiso.py          # NYISO prices, load, forecasts and fuel mix (US)
│   ├── nasapower.py      # NASA POWER meteorology and solar data (global)
│   └── entsog.py         # ENTSOG Transparency Platform (EU gas)
└── utils/
    ├── time.py           # parse_dt, normalise_index
    └── validation.py     # resolve_zone, validate_date_range

Plugin system

External providers subclass DataProvider, declare their zones() and capabilities(), and self-register on import. Providers whose capabilities have different geographical coverage can additionally override capability_zones():

from clarigrid.core.interface import DataProvider
from clarigrid.core.registry import register_provider
import pandas as pd

class NordpoolProvider(DataProvider):
    def zones(self) -> set[str]:
        return {"NO1", "NO2", "SE1", "SE2", "DK1", "DK2", "FI"}

    def capabilities(self) -> set[str]:
        return {"prices"}

    def get_prices(self, zone, start, end, **kwargs) -> pd.DataFrame: ...

register_provider("nordpool", NordpoolProvider())

After cg.connect("nordpool"), calls to cg.get_prices("NO1", …) route to this provider automatically.

---

Development

git clone https://github.com/clarigrid/clarigrid
cd clarigrid
pip install -e ".[dev]"
pytest
ruff check .
mypy clarigrid

---

License

Apache 2.0 — see LICENSE.

Copyright (c) 2026 Alexander Hoogsteyn.