Eco Router MCP server

Eco Router MCP

An MCP server that helps AI agents pick the lowest-carbon cloud region for a workload.

The same GPU job can emit several times more CO₂ depending on which grid powers the datacenter. Eco Router maps AWS, Google Cloud and Azure regions to the electricity grids they draw from, so an agent can ask:

"Where should I run this training job? Data must stay in the EU and latency

should be under 150 ms."

and get back a ranked shortlist with the reasoning behind it.

Carbon figures are location-based grid averages. They describe the grid that supplies each region, not the renewable energy a provider buys, so regions in the same grid get the same value. See what the numbers represent.

Status: early release (v0.1). Corrections and feedback are welcome in

issues. See

Roadmap.

Install

Requires Node.js 22 or later.

Claude Code

claude mcp add eco-router -- npx -y eco-router-mcp

Claude Desktop (claudedesktopconfig.json)

{
  "mcpServers": {
    "eco-router": {
      "command": "npx",
      "args": ["-y", "eco-router-mcp"],
      "env": { "ELECTRICITY_MAPS_API_TOKEN": "optional" }
    }
  }
}

Live grid data (optional)

Out of the box, Eco Router uses annual averages (per grid in the US, per province in Canada, per country elsewhere), so it works with no setup. For hourly, grid-level data, set ELECTRICITYMAPSAPI_TOKEN to your own Electricity Maps API token. Zones your plan does not cover fall back to the annual average automatically.

Your use of live data is governed by your own Electricity Maps plan and its terms. At the time of writing, Electricity Maps offers free access for academic and personal non-commercial use, and a 14-day trial for commercial evaluation. Commercial use requires a paid license. Eco Router does not provide or share any token.

Tools

countries accepts ISO 3166-1 alpha-2 codes and the groups EU and EEA.

Example request to rank_regions:

{
  "countries": ["EU"],
  "origin": { "lat": 50.11, "lon": 8.68 },
  "maxLatencyMs": 40,
  "energyKwh": 500
}

Example request to findcleanwindow for a 6-hour job that must finish within two days:

{
  "countries": ["DE", "FR", "SE"],
  "durationHours": 6,
  "withinHours": 48,
  "energyKwh": 500,
  "timezone": "Australia/Brisbane"
}

Scoring, data sources and their limits are explained in docs/methodology.md.

How regions are mapped to grids, and which mappings rest on assumptions, is documented in docs/regions.md.

Roadmap

Shortened. The full README is on GitHub.