The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gridcarbon MCP listing page.
Official client libraries for the gridcarbon API — hourly electricity grid carbon intensity in gCO2eq/kWh for 45 zones across Europe, the United States and Great Britain.
No API key. No signup. Open CORS.
| Package | Registry | Install |
|---|---|---|
python/ | PyPI gridcarbon | pip install gridcarbon |
typescript/ | npm gridcarbon | npm install gridcarbon |
mcp/ | npm gridcarbon-mcp | npx gridcarbon-mcp |
Both SDKs have zero runtime dependencies — the Python one uses urllib, the
TypeScript one uses global fetch. The MCP server depends on the official
MCP SDK; that cost is documented in its README.
Great Britain is measured on a different basis. GB figures come from NESO and use
operational (combustion-only) emission factors — wind, solar, nuclear and hydro count
as zero. Every other zone uses IPCC AR5 lifecycle factors, where those sources are not
zero. GB is therefore structurally lower than a lifecycle number for the same physical
grid. Do not rank GB against the other 44 zones. Both SDKs expose this as
is_lifecycle / isLifecycle on every reading, and the MCP server excludes GB from
rankings with an explanation rather than silently mixing bases.
"Latest" means newest published, not now. European zones typically run 2–4 hours behind and US zones 11–28 hours behind, because that is when the upstream operators publish. Every reading carries its interval start; use it rather than assuming the value is current.
The full method, the complete emission factor table, and a candid list of known biases are at gridcarbon.dev/methodology.
Pre-alpha. History is uneven by region: Great Britain from 2017-09, the 11 US zones from 2019-01, and the 33 European zones from 2024-08 (two years). It grows
hourly. One limit is configured: 60 requests per minute per IP, loosely enforced — Cloudflare's is deliberately permissive and eventually consistent — each isolate counts separately — so bursts well above that usually succeed. Measured 2026-09-01: 150 requests in 14 seconds from one IP, no 429. Treat 60/min as the intent, not the ceiling, and do not build against the headroom.
Please do not poll faster than every five minutes — that is the Cache-Control max-age
on /v1/intensity/latest, and the data only changes hourly. Breaking changes are possible before 1.0; they will be noted in
each package's changelog.
The data these clients retrieve is derived from:
gridcarbon is not endorsed by, sponsored by, or affiliated with any of these organisations. If you redistribute or display these values, carry the same attribution.
Client code in this repository: MIT. The derived intensity values served by the API: CC BY 4.0.
The data terms, the required attribution notice, the upstream sources and their non-endorsement statements are all in DATA-LICENSE.md.
A fixed, citable snapshot of the data (1,460,467 hourly values to 2026-09-04) is archived on Zenodo: doi:10.5281/zenodo.22299989 (CC BY 4.0); the concept DOI 10.5281/zenodo.22299988 always resolves to the latest snapshot. Machine-readable metadata is in CITATION.cff at the repository root.
Corrections to the method are genuinely welcome — especially from people who work with grid data professionally. The emission factors and their known biases are documented openly precisely so they can be argued with.
Issues and pull requests are the best channel. This repository holds the client libraries; the API backend is not open source.