8000 GitHub - adeelahmedcsku/ghg-calculator: GHG Protocol emissions calculator with 967 embedded factors, CLI, MCP server, and Claude Code skill · GitHub
[go: up one dir, main page]

Skip to content

About

GHG Protocol emissions calculator with 967 embedded factors, CLI, MCP server, and Claude Code skill

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

GHG Emissions Calculator

The open-source GHG Protocol Corporate Standard calculator with 967 embedded emission factors, a CLI, an MCP server, and a Claude Code skill.

Calculate greenhouse gas emissions across all three scopes — from a single natural gas bill to an entire corporate carbon inventory — without paid APIs, proprietary databases, or spreadsheet templates.

Python 3.11+ License: MIT Tests: 92 passing Emission Factors: 967


What This Tool Does

ghg-calculator is a complete GHG Protocol implementation that:

  1. Calculates emissions for any fuel, electricity, refrigerant, material, or spend category
  2. Covers all 3 scopes — Scope 1 (direct combustion, fugitive), Scope 2 (purchased electricity with dual location + market-based), Scope 3 (all 15 value chain categories)
  3. Ships 967 emission factors from 6 free, peer-reviewed databases — no API keys needed
  4. Generates interactive HTML reports with Plotly charts (scope donut, waterfall, treemap, trend lines)
  5. Works as a Claude Code skill — type /ghg-analyze to research and calculate emissions for any scenario

Quick Start

# Install (requires Python 3.11+ and uv)
git clone https://github.com/starrybodies/ghg-calculator.git
cd ghg-calculator
uv sync

# Calculate emissions from 1,000 therms of natural gas
uv run ghg calculate --scope 1 --category stationary_combustion \
  --fuel natural_gas --quantity 1000 --unit therm
# → 5,307 kg CO2e (5.3 tCO2e)

# Search the emission factor database
uv run ghg factors "diesel"

# Generate an HTML report from activity data
uv run ghg report sample.json --output report.html
open report.html

Claude Code Skill: /ghg-analyze

The fastest way to calculate emissions for any scenario. Install once, use from any project:

# Install the skill globally
cp -r .claude/skills/ghg-analyze ~/.claude/skills/

Then use natural language to analyze anything:

/ghg-analyze hyperscaler data center buildout in Texas 2025
/ghg-analyze my company's 200-truck diesel fleet in Ohio
/ghg-analyze Bitcoin mining operation 50MW in Iceland
/ghg-analyze commercial real estate portfolio 500,000 sqft in NYC
/ghg-analyze semiconductor fab construction in Arizona

What the skill does automatically:

  • Researches real-world data for your scenario (electricity rates, fuel consumption, grid factors)
  • Builds structured activity records across all applicable scopes
  • Runs calculations with per-gas breakdown (CO2, CH4, N2O)
  • Generates an interactive HTML report with charts
  • Summarizes results with context comparisons (e.g., "equivalent to X passenger cars")

Emission Factor Database (967 Factors)

All factors are embedded as versioned JSON — no external API calls, no rate limits, no costs.

Source Factors Coverage Use Case
EPA Hub 113 US stationary/mobile combustion, refrigerants Scope 1: natural gas, diesel, gasoline, propane, jet fuel
eGRID 122 US electricity grid (27 subregions) Scope 2: US electricity by region (ERCT, CAMX, RFCE, etc.)
DEFRA 117 UK/international transport, materials, waste Scope 1/3: vehicles, flights, shipping, construction materials
USEEIO 264 US spend-based by NAICS sector Scope 3: purchased goods/services via economic input-output
Ember 120 International electricity (120 countries) Scope 2: global electricity by country (GB, DE, CN, JP, etc.)
EXIOBASE 231 Multi-regional input-output (EU, CN, JP, IN, BR, RU) Scope 3: international spend-based estimates

Reference Emission Factors

Activity Factor Source
Natural gas 5.3 kg CO2e/therm EPA Hub
Diesel 10.21 kg CO2/gallon EPA Hub
Gasoline 8.78 kg CO2/gallon EPA Hub
US grid average 0.37 kg CO2/kWh eGRID
ERCOT (Texas) 0.37 kg CO2/kWh eGRID
CAMX (California) 0.24 kg CO2/kWh eGRID
UK grid 0.21 kg CO2/kWh Ember
Germany grid 0.35 kg CO2/kWh Ember

Use Cases

Corporate Sustainability Teams

Calculate your organization's full Scope 1 + 2 + 3 carbon footprint for annual ESG reporting. Build activity records from utility bills, fleet data, and procurement spend, then generate GHG Protocol-compliant reports.

# Validate your activity data
uv run ghg validate company_2025.json

# Generate a corporate inventory report
uv run ghg report company_2025.json --output "Annual GHG Report 2025.html" \
  --title "Acme Corp GHG Inventory 2025"

ESG Consultants

Run emissions analyses for multiple clients using the same standardized methodology. The embedded factor database means no per-client API costs. Export to GHG Protocol, CDP, or GRI 305 formats.

Climate Tech Developers

Integrate the MCP server or Python API into your own applications. The calculation engine is fully programmable:

from ghg_calculator.engine.calculator import GHGCalculator
from ghg_calculator.models.activity import ActivityRecord

calc = GHGCalculator()
result = calc.calculate_single(ActivityRecord(
    scope="scope_2",
    quantity=1_000_000,
    unit="kWh",
    grid_subregion="ERCT"
))
print(f"{result.total_co2e_tonnes:,.0f} tCO2e")

AI Agent Integration

Use the MCP server to give any AI agent access to emissions calculations:

uv run ghg-mcp  # Starts the MCP server with 8 tools

Tools available: calculate_emissions, calculate_single, get_emission_factors, list_scopes, list_factor_sources, generate_report, get_gwp_values, convert_units

Education and Research

Study GHG Protocol methodology with a transparent, open-source implementation. Every calculation shows the factor used, the source database, and the per-gas breakdown.

Scenario Modeling

Compare emissions across different energy mixes, locations, or operational choices:

# Texas data center on ERCOT grid
uv run ghg calculate --scope 2 --quantity 1000000 --unit kWh --region ERCT
# → 373 tCO2e

# Same data center in California (CAMX)
uv run ghg calculate --scope 2 --quantity 1000000 --unit kWh --region CAMX
# → 241 tCO2e

CLI Reference

ghg calculate — Calculate emissions for a single activity

uv run ghg calculate --scope 1 --category stationary_combustion \
  --fuel natural_gas --quantity 1000 --unit therm

Options: --scope, --category, --fuel, --quantity, --unit, --region, --custom-factor, --json

ghg factors — Search the emission factor database

uv run ghg factors "natural gas"
uv run ghg factors "diesel" --source epa_hub
uv run ghg factors "electricity" --source egrid

ghg gwp — Look up Global Warming Potential values

uv run ghg gwp co2        # → 1
uv run ghg gwp ch4        # → 28 (AR5)
uv run ghg gwp r-410a     # → 2088

ghg convert — Convert between units

uv run ghg convert 1000 therm MWh    # → 29.31 MWh
uv run ghg convert 1 short_ton kg    # → 907.18 kg

ghg validate — Validate a JSON activity file

uv run ghg validate my_activities.json

ghg report — Generate an interactive HTML report

uv run ghg report activities.json --output report.html --title "2025 GHG Inventory"

Activity Record Format

Every calculation starts with an activity record — a JSON object describing what happened:

Scope 1: Direct Emissions

{
  "scope": "scope_1",
  "scope1_category": "stationary_combustion",
  "fuel_type": "natural_gas",
  "quantity": 1000,
  "unit": "therm"
}

Categories: stationary_combustion, mobile_combustion, fugitive_emissions, process_emissions

Fuel types: natural_gas, diesel, gasoline, propane, jet_fuel, kerosene, coal_bituminous, fuel_oil_2, fuel_oil_6, lpg, ethanol, biodiesel

Refrigerants: r-410a, hfc-134a, r-404a, r-407c, r-507a, r-32, and 20+ more

Scope 2: Purchased Electricity

{
  "scope": "scope_2",
  "quantity": 500000,
  "unit": "kWh",
  "grid_subregion": "ERCT"
}

US eGRID subregions: AKGD, AKMS, AZNM, CAMX, ERCT, FRCC, HIMS, HIOA, MROE, MROW, NEWE, NWPP, NYCW, NYLI, NYUP, PRMS, RFCE, RFCM, RFCW, RMPA, SPNO, SPSO, SRMV, SRMW, SRSO, SRTV, SRVC

International (120 countries): use "country": "GB" instead of grid_subregion

Scope 2 automatically produces both location-based and market-based results per GHG Protocol Scope 2 Guidance.

Scope 3: Value Chain

{
  "scope": "scope_3",
  "scope3_category": 1,
  "quantity": 1000000,
  "unit": "USD",
  "spend_amount": 1000000,
  "naics_code": "334111"
}

All 15 Scope 3 categories supported:

  1. Purchased goods and services
  2. Capital goods
  3. Fuel- and energy-related activities
  4. Upstream transportation
  5. Waste generated in operations
  6. Business travel
  7. Employee commuting
  8. Upstream leased assets
  9. Downstream transportation
  10. Processing of sold products
  11. Use of sold products
  12. End-of-life treatment
  13. Downstream leased assets
  14. Franchises
  15. Investments

How It Works

Core Formula

CO2e = Activity Data × Emission Factor × Global Warming Potential

For each activity, the calculator:

  1. Matches an emission factor from the 967-factor database (by fuel type, region, category, or NAICS code)
  2. Converts units using pint (handles therms ↔ kWh ↔ MMBtu ↔ MJ, gallons ↔ litres, short tons ↔ tonnes, etc.)
  3. Calculates per-gas emissions — CO2, CH4, and N2O are computed separately
  4. Applies GWP conversion — each gas is converted to CO2-equivalent using AR5 or AR6 Global Warming Potentials
  5. Aggregates results — totals by scope, category, and gas type

GWP Values (AR5)

Gas GWP (100-year)
CO2 1
CH4 28
N2O 265
HFC-134a 1,300
R-410A 2,088
SF6 23,500

Both AR5 and AR6 assessment reports are supported. AR5 is the default per current GHG Protocol guidance.


MCP Server

The MCP server exposes the full calculator to any AI agent or MCP-compatible client:

uv run ghg-mcp

Available Tools

Tool Description
calculate_emissions Calculate emissions for multiple activities
calculate_single Calculate emissions for one activity
get_emission_factors Search and retrieve emission factors
list_scopes List available scopes and categories
list_factor_sources List all factor databases and their coverage
generate_report Generate an HTML report from activity data
get_gwp_values Look up GWP for any greenhouse gas
convert_units Convert between energy, mass, and volume units

MCP Configuration

Add to your Claude Code or MCP client configuration:

{
  "mcpServers": {
    "ghg-calculator": {
      "command": "uv",
      "args": ["--directory", "/path/to/ghg-calculator", "run", "ghg-mcp"]
    }
  }
}

Comparison with Alternatives

Feature ghg-calculator Climatiq API Spreadsheets Persefoni/Sweep
Price Free (MIT) $0.01/calc Free $50K+/year
Emission factors 967 embedded 40,000+ (API) Manual entry Proprietary
Offline capable Yes No Yes No
API keys required No Yes N/A Yes
All 3 scopes Yes Yes Manual Yes
Dual Scope 2 Automatic Manual Manual Yes
Per-gas breakdown Yes Some No Yes
AI agent integration MCP + Skill REST API No No
Open source Yes No N/A No
Interactive reports Plotly HTML No Charts Dashboard

Frequently Asked Questions

How do I calculate Scope 3 emissions?

Scope 3 covers your value chain — everything from purchased goods (category 1) to investments (category 15). The easiest method is spend-based: provide your procurement spend in USD with a NAICS code, and the calculator uses USEEIO input-output factors. For more accuracy, use activity-based methods with specific quantities (tonnes of steel, km of transport, etc.) and custom emission factors.

What emission factor databases are included?

Six free, peer-reviewed databases: EPA Emission Factors Hub (US combustion), eGRID (US electricity grid), DEFRA (UK government factors for transport, materials, waste), USEEIO (US economic input-output), Ember (international electricity for 120 countries), and EXIOBASE (multi-regional input-output for EU, China, Japan, India, Brazil, Russia).

How accurate are the calculations?

The calculator follows GHG Protocol Corporate Standard methodology exactly. Accuracy depends on your input data quality. Calculations using direct activity data (fuel consumption, meter readings) with source-specific factors are the most accurate. Spend-based Scope 3 estimates are inherently less precise but useful for screening.

Can I add custom emission factors?

Yes. Use the custom_factor field on any activity record to provide your own kg CO2e per unit value. This overrides the database lookup.

What units are supported?

Energy: kWh, MWh, therm, MMBtu, MJ, GJ, CCF, MCF. Mass: kg, tonne, short_ton, lb. Volume: gallon, litre, barrel. Distance: km, mile. Currency: USD. The pint-based converter handles all standard conversions automatically.

How does dual Scope 2 work?

Every electricity activity automatically produces two results: location-based (using the grid average for your region) and market-based (using your supplier's specific factor, or the residual mix if none provided). This follows GHG Protocol Scope 2 Guidance requirements.


Architecture

src/ghg_calculator/
├── models/          # Pydantic data models (activity, factors, results, quality)
├── factors/         # Emission factor database (967 factors in versioned JSON)
│   ├── registry.py  # Factor search and retrieval
│   ├── gwp.py       # AR5 + AR6 Global Warming Potential tables
│   └── data/        # EPA Hub, eGRID, DEFRA, USEEIO, Ember, EXIOBASE
├── engine/          # Calculation engine (Strategy pattern)
│   ├── calculator.py  # Orchestrator
│   ├── scope1/      # Stationary, mobile, fugitive, process
│   ├── scope2/      # Location-based + market-based electricity
│   └── scope3/      # All 15 value chain categories
├── units/           # pint-based unit converter
├── reporting/       # Plotly charts + Jinja2 HTML templates
├── cli/             # Typer CLI (ghg command)
└── mcp/             # FastMCP server (ghg-mcp command)

Development

# Install with dev dependencies
uv sync

# Run all 92 tests
uv run pytest

# Run specific test suites
uv run pytest tests/unit/          # 46 unit tests
uv run pytest tests/integration/   # 15 integration tests
uv run pytest tests/e2e/           # 17 end-to-end CLI tests

# Lint
uv run ruff check src/

Dependencies

  • pydantic — data validation and models
  • pint — unit conversion
  • pandas — summary tables
  • plotly — interactive charts
  • typer + rich — CLI interface
  • fastmcp — MCP server
  • jinja2 — HTML report templates

License

MIT — free for commercial and personal use.


Built for the GHG Protocol Corporate Standard. 967 emission factors. Zero API costs. One command.

About

GHG Protocol emissions calculator with 967 embedded factors, CLI, MCP server, and Claude Code skill

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0