Provides carbon-aware ranking of Google Cloud regions, enabling selection of low-carbon regions based on grid carbon intensity and optional latency constraints.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@eco-router-mcp Rank EU regions for a GPU job, latency under 100ms."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Requires Node.js 22 or later.
Claude Code
claude mcp add eco-router -- npx -y eco-router-mcpClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"eco-router": {
"command": "npx",
"args": ["-y", "eco-router-mcp"],
"env": { "ELECTRICITY_MAPS_API_TOKEN": "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 ELECTRICITY_MAPS_API_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.
Related MCP server: ebb-ai
Tool | What it does |
| Ranks regions by grid carbon intensity, optionally balanced against estimated latency from an |
| For flexible batch jobs, finds the start time in the next 72 hours with the lowest forecast carbon intensity in each grid zone, and the savings compared with starting now. Requires |
| Lists cloud regions and the grid zone each one draws power from. Filter by |
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 find_clean_window 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.
MCP server skeleton over stdio
Full AWS, Google Cloud and Azure region dataset with sources
Carbon data: published annual averages by default, live data with an optional Electricity Maps API token
rank_regions: rank regions by carbon intensity and estimated latency,
with hard limits such as allowed countries or a carbon ceiling
US grid-level annual data without a token (EPA eGRID)
Canadian provincial annual data without a token (National Inventory Report)
Grid-level annual data for Australia
Time shifting: suggest when to run, using carbon forecasts
Publish to npm and the MCP Registry
npm install
npm test # unit tests, no network needed
npm run typecheck
npm run build # compiles to dist/
npm run dev # runs the server over stdio from source
npm run update:baseline # refreshes national averages from Ember
npm run update:egrid # refreshes US grid averages from EPA eGRID
npm run update:canada # refreshes Canadian provincial averagesAnnual carbon intensity: Ember, Yearly Electricity Data, licensed under CC BY 4.0.
US grid generation mix: US EPA eGRID (public domain), converted to lifecycle emissions with Ember's US factors.
Canadian provincial generation mix: Environment and Climate Change Canada, National Inventory Report, Annex 7, converted to lifecycle emissions with Ember's Canadian factors. Contains information licensed under the Open Government Licence – Canada.
Live carbon intensity (optional): Source: ElectricityMaps.com, using your own API token and subject to the terms of your plan.
Region lists: official AWS, Google Cloud and Azure documentation. See docs/regions.md.
Corrections to region data are especially welcome. See CONTRIBUTING.md to get started.
Eco Router started as a hackathon project. Thanks to the original team for the scoring design this project builds on: Chris (@chrislee021225), Joli (@L-Joli), Bob (@Loic0927), Irene Tsai (@YunTong09) and Steven Su (@stevensu04).
For flexible batch jobs, find when in the next hours (up to 72) each candidate region's grid is forecast to be cleanest, and how much that saves compared with starting now. Local times default to this computer's time zone. Needs ELECTRICITY_MAPS_API_TOKEN with forecast access. Limit candidates with regions, providers or countries (at most 15 grid zones per call).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many options to return. Default 5. | |
| regions | No | Candidate regions as provider/id, e.g. ["aws/eu-north-1", "gcp/europe-west9"]. Tip: shortlist with rank_regions first. | |
| timezone | No | IANA time zone for local start times, e.g. "Australia/Brisbane". Defaults to the time zone of the computer running Eco Router; set it when the user is elsewhere. | |
| countries | No | Only consider regions in these countries or groups (EU, EEA). | |
| energyKwh | No | Estimated job energy, to report emissions for each option. | |
| providers | No | Only consider these cloud providers. | |
| withinHours | No | The job must finish within this many hours from now. Default 24, max 72. | |
| durationHours | Yes | How long the job runs, in whole hours. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| results | Yes | |
| timezone | Yes | |
| generatedAt | Yes | |
| unavailable | Yes | |
| withinHours | Yes | |
| durationHours | Yes | |
| evaluatedZones | Yes | |
| timezoneSource | Yes | |
| evaluatedRegions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations providing readOnlyHint=true and openWorldHint=true, the description adds valuable behavioral context: it discloses the auth requirement ('Needs ELECTRICITY_MAPS_API_TOKEN with forecast access'), the default timezone behavior ('Local times default to this computer's time zone'), and a hard call limit ('at most 15 grid zones per call'). No contradiction with the annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the first states the core behavior and output, the second covers the timezone default, and the third covers auth and limits. The most important information is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (8 parameters, output schema present, annotations covering safety), the description supplies the key missing context: purpose, audience (flexible batch jobs), auth needs, default timezone, and the 15-zone cap. Since an output schema exists, return-value explanation is unnecessary. The definition is fully sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by specifying a cross-parameter constraint ('Limit candidates with regions, providers or countries (at most 15 grid zones per call)') and clarifying the local-time default behavior, which affects the timezone parameter. This adds meaning rather than merely repeating the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'find when ... each candidate region's grid is forecast to be cleanest, and how much that saves compared with starting now.' It clearly targets flexible batch jobs, which distinguishes it from the sibling list_regions and rank_regions operations without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description opens with 'For flexible batch jobs,' giving clear context for when the tool is appropriate. It does not explicitly say when not to use it or contrast with siblings, though the schema's regions parameter adds a 'Tip: shortlist with rank_regions first,' which points to a related workflow. The guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the cloud regions Eco Router knows about, with the electricity grid zone each one draws power from.
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Only return regions in this country (ISO 3166-1 alpha-2, e.g. "DE") or group (EU, EEA). | |
| provider | No | Only return regions from this cloud provider. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| regions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds one useful behavioral detail: each region is paired with its electricity grid zone. It does not discuss result ordering, pagination, or data source quirks, but for a simple read-only listing this is acceptable; a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero filler. It front-loads the action and resource, then appends the key output detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, rich annotations, 100% schema coverage, and existing output schema, the description is nearly complete. The only gap is the absence of explicit routing versus sibling tools, but this does not block correct invocation for the main use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both optional filter parameters (country, provider) are fully documented in the schema. The description itself adds no additional parameter-level meaning, so it sits at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a concrete resource ('cloud regions Eco Router knows about') and states the key distinguishing output ('electricity grid zone'). This clearly separates it from siblings like rank_regions and find_clean_window, which imply different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for listing all known cloud regions, but it never explicitly states when to prefer this over rank_regions or find_clean_window, nor does it mention any exclusions. The usage context is clear but the alternatives are only inferable from sibling names, not articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank AWS, Google Cloud and Azure regions for a workload by the carbon intensity of their electricity grid, optionally balanced against estimated latency from an origin. Supports hard limits for allowed countries, maximum latency and maximum carbon intensity. Read notes before relying on close scores.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many regions to return. Default 5. | |
| origin | No | Where users or data are. Enables latency estimates and latency weighting. | |
| countries | No | Only consider regions in these countries or groups (EU, EEA), e.g. ["EU"] for EU data residency. Default: all. | |
| energyKwh | No | Estimated job energy, to report emissions per region. | |
| providers | No | Only consider these cloud providers. Default: all. | |
| carbonWeight | No | Weight on carbon versus latency, 0..1. Default 0.7. Only used with origin. | |
| maxLatencyMs | No | Exclude regions estimated slower than this round trip. Requires origin. | |
| maxCarbonIntensity | No | Exclude regions above this carbon intensity, gCO2e/kWh. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| results | Yes | |
| excluded | Yes | |
| evaluated | Yes | |
| qualified | Yes | |
| generatedAt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavior beyond the readOnlyHint annotation: the ranking is based on electricity-grid carbon intensity, latency is 'estimated' from an origin, and the filters are 'hard limits'. The warning to 'Read notes before relying on close scores' is a valuable behavioral caveat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary purpose and criterion are front-loaded in the first sentence, and the second sentence adds constraint types and a specific caveat. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter ranking tool with 100% schema coverage and an output schema, the description covers providers, ranking basis, optional latency, constraint types, and the main caveat. It does not need to document every parameter because the schema already does so.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description summarizes hard limits for countries, latency, and carbon intensity, but does not add detail beyond what each parameter schema already states. It does not repeat or undermine the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Rank'), a concrete resource ('AWS, Google Cloud and Azure regions'), and a clear criterion (carbon intensity, optionally balanced against latency). This clearly differentiates it from sibling tools like list_regions and find_clean_window.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives useful context: ranking is for 'a workload' with optional latency balancing and hard constraints. However, it does not explicitly state when to prefer this tool over its siblings, nor when not to use it, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_clean_windowlist_regionsrank_regionsScored across 3 tools
Each tool has a distinct purpose: listing known regions, ranking regions for a workload, and finding optimal start times for batch jobs. There is no overlap in what they return or when an agent would choose one over another.
All three tool names follow a consistent verb_noun pattern: list_regions, rank_regions, find_clean_window. The verbs clearly indicate the action and the nouns indicate the object.
Three tools is on the low end, but the server has a focused purpose: carbon-aware region selection. Each tool covers a distinct stage of that workflow, so the count feels appropriate rather than thin.
The tool surface covers the core workflow: discover regions, rank them for a workload, and find clean windows for flexible jobs. A minor gap is the lack of a tool to fetch detailed grid data for a single region, but agents can work around it with list_regions and rank_regions.
Carbon-accounted agent compute: free footprints; certificates backed by real offset retirement.
Solar, weatherization, EV charging, battery and heat-pump decision tools for AI agents.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
The cloud for agents. Tools for AI agents to register, build, and deploy other agents. Zero human required.
