eco2mix-mcp — Carbon-Aware Kiro 🌱⚡

eco2mix-mcp is a custom MCP server that connects Kiro to the French power grid in real time (RTE éCO2mix open data: carbon intensity, consumption, generation mix — no API key needed). Paired with a steering rule, it makes Kiro carbon-aware: before launching a heavy job (test suite, docker build, batch), Kiro checks the live grid and answers GO or DEFER. Run your builds when the electrons are clean.

Built for Day 5 of the Kiro Birthday challenge (https://kiro.dev/birthday/): "Build a custom MCP integration".

How Kiro was used

Kiro was used end-to-end, spec-first. The .kiro/specs/eco2mix-mcp/ folder contains the requirements (EARS-style acceptance criteria), the design (architecture, thresholds, error handling), and the task list that drove the build — from validating the ODRE open-data API (including its trap: future 15-minute slots exist with null values and must be filtered) to implementing and testing the server.

The MCP server is built with the official Python MCP SDK (FastMCP, stdio transport). The pure logic is covered by 8 unit tests; the MCP handshake and each tool were verified against the real API before wiring anything into Kiro.

The integration is registered in .kiro/settings/mcp.json, so Kiro spawns the server automatically. The interesting part is .kiro/steering/carbon-aware.md: it instructs Kiro to call should_i_run_now before launching any heavy command (full test suite, docker build, batch job, model training) and to act on the verdict — GO when the grid is CLEAN, defer when fossil peakers push the intensity up. In the demo, Kiro is asked whether it should run a full test suite and docker build now: it calls the tool, reads 11 gCO2/kWh (CLEAN, stable trend over the last 2 hours), and answers GO with its reasoning. This is something Kiro fundamentally could not do without the integration: no training data can know the state of the power grid right now.

What it connects to

RTE éCO2mix real-time national data, served by the ODRE open-data platform (dataset eco2mix-national-tr). Live, 15-minute resolution: electricity consumption, carbon intensity (gCO2eq/kWh), and the full generation mix (nuclear, wind, solar, hydro, gas, coal, oil, bioenergy).

No API key. No secrets. Public open data (Etalab open licence).

Why it matters: an LLM's training data can never know that the French grid is at 11 gCO2/kWh right now because solar is peaking. This integration gives Kiro that knowledge — and something it genuinely could not do without it.

Tools

Tool	What Kiro gets
get_current_grid	Full live snapshot: consumption, intensity, generation mix
get_carbon_intensity	gCO2/kWh + verdict: CLEAN / MODERATE / DIRTY
get_mix_breakdown	Generation by source (MW), low-carbon & renewable shares
should_i_run_now	GO / GO_WITH_CAUTION / DEFER for a heavy job + 2h trend

What I built with it: a carbon-aware Kiro

.kiro/steering/carbon-aware.md instructs Kiro to call should_i_run_now before launching any heavy command (full test suite, docker build, batch job, model training) and to act on the recommendation:

• 🟢 GO — grid is clean, run it (and say the current intensity)
• 🟡 GO_WITH_CAUTION — urgent work only
• 🔴 DEFER — fossil peakers running; Kiro proposes to wait for a cleaner window using the 2-hour trend

Shifting deferrable compute to low-carbon windows is one of the simplest green-IT practices. This project makes Kiro apply it automatically.

Beyond the demo: a local build is just the illustration — its footprint is symbolic. The pattern is what scales: CI/CD farms, data batch jobs, ML training, any deferrable workload that can slide a few hours into a low-carbon window. This is the core idea of carbon-aware computing, applied to a coding agent.

Setup

git clone https://github.com/el-pedrito/eco2mix-mcp.git
cd eco2mix-mcp
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/pytest tests/    # 8 tests, no network needed

The server is registered for Kiro in .kiro/settings/mcp.json (stdio):

{
  "mcpServers": {
    "eco2mix": {
      "command": ".venv/bin/python",
      "args": ["server/eco2mix_mcp.py"]
    }
  }
}

Open Kiro in this folder and ask:

"Should I run my full test suite and docker build now?"

Kiro calls the MCP server, which queries the live grid, and answers with the current carbon intensity, the trend, and a go/defer recommendation.

Configuration (optional, no secrets)

See .env.example. Everything works with zero configuration; you can tune thresholds and timeouts via environment variables:

Variable	Default	Purpose
ECO2MIX_CLEAN_THRESHOLD	25	Max gCO2/kWh for a CLEAN verdict
ECO2MIX_MODERATE_THRESHOLD	60	Max gCO2/kWh for MODERATE
ECO2MIX_TIMEOUT_S	15	HTTP timeout
ECO2MIX_API_BASE	ODRE endpoint	Override the data endpoint

Demo

Kiro calls the eco2mix MCP server, which queries the live French grid, and decides whether to run the heavy job — end-to-end (MCP server → ODRE API → live grid data → Kiro's decision). Full-quality video (mp4, 65s).

Project structure

server/eco2mix_mcp.py     # the MCP server (FastMCP, stdio, ~180 lines)
tests/test_eco2mix.py     # unit tests on the pure logic
.kiro/settings/mcp.json   # Kiro wiring
.kiro/steering/carbon-aware.md   # the carbon-aware behavior
.kiro/specs/eco2mix-mcp/  # the Kiro spec that drove the build

Data & licence

Data: RTE éCO2mix via ODRE, Etalab open licence. Scope: France national grid. Carbon intensity method: RTE.