Tutorial: Electricity Maps

Environment

Data source: Electricity Maps

Overview

Electricity Maps wraps Electricity Maps, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-electricity-maps": {
      "url": "https://context.gnist.ai/mcp/electricity-maps/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_carbon_intensity`

Get the carbon intensity of electricity production for a grid zone. Carbon intensity measures how much CO₂-equivalent is emitted per kWh of electricity consumed, expressed in gCO₂eq/kWh. Lower is greener. Args: zone: Electricity Maps zone code (e.g. "NO", "DE", "FR", "GB", "US-CAL-CISO"). See https://app.electricitymaps.com for a full list of zone codes. datetime: Optional ISO 8601 datetime string to look up historical intensity. If omitted, returns the latest available value. Historical data covers approximately the past 24 hours. Returns: Carbon intensity in gCO₂eq/kWh with zone, timestamp, and estimation metadata.

Parameter	Type	Required	Description
`zone`	string	required	Electricity Maps zone code (e.g. "NO", "DE", "FR", "GB", "US-CAL-CISO"). See https://app.electricitymaps.com for a full list of zone codes.
`datetime`	any	optional	Optional ISO 8601 datetime string to look up historical intensity. If omitted, returns the latest available value. Historical data covers approximately the past 24 hours.

curl -X POST "https://context.gnist.ai/mcp/electricity-maps/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_carbon_intensity", "arguments": {"zone": "NO"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/electricity-maps/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'zone': 'NO'}, 'name': 'get_carbon_intensity'}},
)
print(resp.json())

`get_grid_mix`

Get the current electricity production breakdown by energy source for a grid zone. Shows how electricity is being generated right now — what percentage comes from renewables, fossil fuels, nuclear, etc. Useful for understanding a region's energy profile or for EU CSRD Scope 2 emissions reporting. Args: zone: Electricity Maps zone code (e.g. "NO", "DE", "FR", "GB", "US-CAL-CISO"). Returns: Production breakdown by source (MW), total production, renewable percentage, fossil-free percentage, and IPCC lifecycle emission factor per source.

Parameter	Type	Required	Description
`zone`	string	required	Electricity Maps zone code (e.g. "NO", "DE", "FR", "GB", "US-CAL-CISO").

curl -X POST "https://context.gnist.ai/mcp/electricity-maps/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_grid_mix", "arguments": {"zone": "NO"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/electricity-maps/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'zone': 'NO'}, 'name': 'get_grid_mix'}},
)
print(resp.json())

`forecast_intensity`

Get predicted carbon intensity for a grid zone over the coming hours. Forecasts are generated by Electricity Maps based on weather models and scheduled generation. Useful for scheduling compute workloads, EV charging, or other deferrable energy consumption to lower-carbon windows. Args: zone: Electricity Maps zone code (e.g. "NO", "DE", "FR", "GB", "US-CAL-CISO"). hours_ahead: How many hours of forecast to return (1–48, default 24). Returns: Hourly forecast entries with predicted carbon intensity in gCO₂eq/kWh.

Parameter	Type	Required	Description
`zone`	string	required	Electricity Maps zone code (e.g. "NO", "DE", "FR", "GB", "US-CAL-CISO").
`hours_ahead`	integer	optional	How many hours of forecast to return (1–48, default 24). (default: `24`)

curl -X POST "https://context.gnist.ai/mcp/electricity-maps/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "forecast_intensity", "arguments": {"zone": "NO"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/electricity-maps/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'zone': 'NO'}, 'name': 'forecast_intensity'}},
)
print(resp.json())

`find_greenest_region`

Compare carbon intensity across multiple grid zones and rank them by greenness. Useful for routing compute workloads, data center jobs, or EV charging to the cleanest available grid. Lower carbon intensity = greener electricity. Args: zones: List of Electricity Maps zone codes to compare (e.g. ["NO", "SE", "FI", "DE", "FR"]). window_hours: Averaging window in hours (1 = current value, default 1). Values > 1 average over recent history for a smoother signal. Returns: Zones ranked from greenest to most carbon-intensive, with intensity values and the recommended zone for low-carbon scheduling.

Parameter	Type	Required	Description
`zones`	list[string]	required	List of Electricity Maps zone codes to compare (e.g. ["NO", "SE", "FI", "DE", "FR"]).
`window_hours`	integer	optional	Averaging window in hours (1 = current value, default 1). Values > 1 average over recent history for a smoother signal. (default: `1`)

curl -X POST "https://context.gnist.ai/mcp/electricity-maps/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "find_greenest_region", "arguments": {"zones": "[\"NO\""}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/electricity-maps/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'zones': '["NO"'}, 'name': 'find_greenest_region'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/electricity-maps/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/electricity-maps/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use find_greenest_region to find items, then get_carbon_intensity to get full details. This two-step pattern is common for exploring data before drilling down.

FAQ

What data does Electricity Maps provide?

Real-time energy grid data — carbon intensity, generation mix, and power breakdown by zone. It exposes 5 tools: get_carbon_intensity, get_grid_mix, forecast_intensity, find_greenest_region, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Electricity Maps API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.