Repository avatar
Other Tools
v1.8.0
active

emission-factors

io.github.rozetyp/emission-factors

Keyless US grid carbon + power cost by ZIP: eGRID Scope 2, Scope 1 fuels, site ranking, clean hours

Documentation

emission-factors MCP server

License: MIT MCP No key required

Give Claude, Cursor, Cline, or any MCP client live access to US electricity data by ZIP code - grid-carbon emission factors, retail rates, hourly grid carbon intensity, power-plant emissions, and utility tariffs.

Backed by emission-factors.com, which wraps EPA eGRID, EIA-861, EIA-930, EPA CAMD, and OpenEI URDB into one ZIP-keyed API.

Free. No API key, no signup. The API is rate-limited per IP (2,000 requests/hour).


What you can ask

Once connected, your agent can answer things like:

  • "My HQ in ZIP 94105 uses 1.2M kWh/year. What's our Scope 2 carbon footprint and annual electricity cost?"
  • "Compare Denver, Austin, and Columbus for a new data center on grid carbon intensity and electricity price."
  • "What hour of the day is cleanest to run a 500 kW batch job in California this week?"
  • "Enrich this list of 40 store ZIP codes with each site's emission factor and carbon-free percentage."
  • "Which are the dirtiest power plants in Texas by CO2 over the last week?"
  • "Rank Ashburn VA, Abilene TX and The Dalles OR for a 10 MW data center on carbon and power cost."
  • "Our plant burns 40,000 therms of gas and 3,000 gallons of diesel a year - what's our Scope 1?"
  • "What's the actual PG&E residential tariff for 94105, not the state average?"

Why use it

  • Scope 2 carbon accounting - GHG Protocol location- and market-based emission factors for 33,700+ US ZIP codes (CDP, CSRD, California SB 253 inputs).
  • Site selection - compare candidate locations on both carbon intensity and electricity cost in one conversation.
  • Demand-response and load-shifting analysis - hourly grid carbon from EIA-930 (fixed per-fuel factors on in-BA generation: for timing, not inventory reporting).
  • Plant-level emissions - EPA CAMD data for fossil units over 25 MW: per-facility summaries or unit-hour records, published quarterly.
  • Agents and automation - a clean tool surface so an LLM can fetch authoritative government data instead of hallucinating factors.

Quick start

There are two ways to run this. Most people want Option A.

Option A - Remote server (recommended, zero install)

Nothing to install, always up to date. The hosted endpoint is https://emission-factors.com/mcp (Streamable HTTP, no key).

Claude (web, desktop app, mobile) - Add to Claude. The link opens Claude's custom-connector dialog with the name and URL filled in; select Add, then Connect. By hand: Customize -> Connectors -> Add custom connector, URL https://emission-factors.com/mcp, OAuth fields empty.

Claude Code

claude mcp add --transport http emission-factors https://emission-factors.com/mcp

Cursor - add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "emission-factors": {
      "url": "https://emission-factors.com/mcp"
    }
  }
}

Cline / Continue / Zed / other clients - add a remote (Streamable HTTP) MCP server with URL https://emission-factors.com/mcp. No key needed.

Claude Desktop's claude_desktop_config.json only starts local (stdio) servers - a "url" entry there does nothing. Use the connector link above, or Option B.

Option B - Local stdio server (this package)

Runs the server as a local process that proxies the same public API. Useful for clients that only support stdio transport, or if you want to self-host.

Run straight from GitHub (builds on install, requires Node 18+):

{
  "mcpServers": {
    "emission-factors": {
      "command": "npx",
      "args": ["-y", "github:rozetyp/emission-factors-mcp"]
    }
  }
}

Or clone and run from source:

git clone https://github.com/rozetyp/emission-factors-mcp.git
cd emission-factors-mcp
npm install        # builds dist/ via the prepare script
{
  "mcpServers": {
    "emission-factors": {
      "command": "node",
      "args": ["/absolute/path/to/emission-factors-mcp/dist/index.js"]
    }
  }
}

Optional environment variable: EMISSION_FACTORS_API_BASE (defaults to https://emission-factors.com) if you run your own instance of the API.


Tools

Eleven tools, keyed by US ZIP code (or a direct code where noted). The remote server and this stdio build expose the same set.

ToolPurposeKey inputs
lookup_emission_factorEPA eGRID CO2e + full generation mix for a ZIPzip
lookup_by_coordinatesSame, resolved from lat/lon via Census geocoderlat, lon
lookup_batchEmission factors for up to 100 ZIPs at oncezips[]
calculate_emissionsScope 2 CO2e for a ZIP + kWh, location-based and market-based (Green-e residual mix)zip, kwh, renewable_kwh
hourly_intensityHourly grid carbon intensity (EIA-930, ~24h lag)zip or ba, hours
plant_emissionsPlant emissions (EPA CAMD): facility summaries or unit-hour recordsfacility_id or state, days
utility_tariffUtility-specific tariff, not state average (OpenEI URDB)zip, utility, or eiaid
electricity_rateState-average retail rate by sector (EIA-861)zip
compare_sitesRank 2-25 candidate sites on grid carbon, $/kWh and cleanest daily windowzips[], annual_kwh, sector
cleanest_hoursCleanest N-hour window of the day to run a flexible load, in local timezip or ba, duration
calculate_fuel_emissionsScope 1 CO2e for fuels burned on site (EPA GHG Emission Factors Hub)items[]: fuel, quantity, unit

All tools return JSON. See full API docs for exact response shapes.


Data sources

DataSourceNotes
Grid emission factorsEPA eGRID2023 Rev2 (+ eGRID2024 from Cornerstone via year=2024)Annual, location-based, 27 subregions
Residual mix (market-based Scope 2)Green-e Residual Mix 2025 (2023 data)Per eGRID subregion
Fuel combustion factors (Scope 1)GHG Emission Factors Hub 2026 (Cornerstone, successor to EPA's Hub); EPA 2025 via edition63 fuels, AR6 GWPs (AR5 for 2025)
Retail electricity ratesEIA Form 861State-level monthly average by sector
Hourly grid carbon intensityEIA-930Derived from hourly fuel mix, ~24h lag
Plant-level emissionsEPA CAMDfossil units >25 MW, published quarterly (45+ days after quarter end)
Utility-specific tariffsOpenEI URDB (NREL)ZIP matched to its utility by EIA ID
ZIP / lat-lon resolutionUS Census (ZCTA + Geocoder)ZIP -> eGRID subregion mapping

Rate limits and auth

  • No API key, no signup. Every request is anonymous.
  • 2,000 requests/hour per IP. Generous for interactive use; if you hit it you get an HTTP 429 with a retryAfter hint.
  • The external-data endpoints are cached server-side (24h rates, 1h hourly intensity, 7d tariffs, 24h plant emissions), so repeated calls are fast and don't burn upstream quotas.

Also available


Development

npm install        # install deps and build (prepare -> tsc)
npm run build      # compile TypeScript to dist/
npm run dev        # watch mode
npm start          # run the built server over stdio

Quick smoke test with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

The server is a thin proxy: each tool maps to one /api/* endpoint on emission-factors.com, validates inputs, and returns the JSON response. There is no local state and no key handling.

License

MIT - see LICENSE. Data belongs to its respective US government sources (EPA, EIA, Census) and NREL/OpenEI; this project and the API are an unofficial wrapper, not affiliated with those agencies.