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.
ghg-calculator is a complete GHG Protocol implementation that:
- Calculates emissions for any fuel, electricity, refrigerant, material, or spend category
- 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)
- Ships 967 emission factors from 6 free, peer-reviewed databases — no API keys needed
- Generates interactive HTML reports with Plotly charts (scope donut, waterfall, treemap, trend lines)
- Works as a Claude Code skill — type
/ghg-analyzeto research and calculate emissions for any scenario
# 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.htmlThe 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")
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 |
| 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 |
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"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.
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")Use the MCP server to give any AI agent access to emissions calculations:
uv run ghg-mcp # Starts the MCP server with 8 toolsTools available: calculate_emissions, calculate_single, get_emission_factors, list_scopes, list_factor_sources, generate_report, get_gwp_values, convert_units
Study GHG Protocol methodology with a transparent, open-source implementation. Every calculation shows the factor used, the source database, and the per-gas breakdown.
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 tCO2euv run ghg calculate --scope 1 --category stationary_combustion \
--fuel natural_gas --quantity 1000 --unit thermOptions: --scope, --category, --fuel, --quantity, --unit, --region, --custom-factor, --json
uv run ghg factors "natural gas"
uv run ghg factors "diesel" --source epa_hub
uv run ghg factors "electricity" --source egriduv run ghg gwp co2 # → 1
uv run ghg gwp ch4 # → 28 (AR5)
uv run ghg gwp r-410a # → 2088uv run ghg convert 1000 therm MWh # → 29.31 MWh
uv run ghg convert 1 short_ton kg # → 907.18 kguv run ghg validate my_activities.jsonuv run ghg report activities.json --output report.html --title "2025 GHG Inventory"Every calculation starts with an activity record — a JSON object describing what happened:
{
"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": "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": "scope_3",
"scope3_category": 1,
"quantity": 1000000,
"unit": "USD",
"spend_amount": 1000000,
"naics_code": "334111"
}All 15 Scope 3 categories supported:
- Purchased goods and services
- Capital goods
- Fuel- and energy-related activities
- Upstream transportation
- Waste generated in operations
- Business travel
- Employee commuting
- Upstream leased assets
- Downstream transportation
- Processing of sold products
- Use of sold products
- End-of-life treatment
- Downstream leased assets
- Franchises
- Investments
CO2e = Activity Data × Emission Factor × Global Warming Potential
For each activity, the calculator:
- Matches an emission factor from the 967-factor database (by fuel type, region, category, or NAICS code)
- Converts units using pint (handles therms ↔ kWh ↔ MMBtu ↔ MJ, gallons ↔ litres, short tons ↔ tonnes, etc.)
- Calculates per-gas emissions — CO2, CH4, and N2O are computed separately
- Applies GWP conversion — each gas is converted to CO2-equivalent using AR5 or AR6 Global Warming Potentials
- Aggregates results — totals by scope, category, and gas type
| 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.
The MCP server exposes the full calculator to any AI agent or MCP-compatible client:
uv run ghg-mcp| 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 |
Add to your Claude Code or MCP client configuration:
{
"mcpServers": {
"ghg-calculator": {
"command": "uv",
"args": ["--directory", "/path/to/ghg-calculator", "run", "ghg-mcp"]
}
}
}| 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 |
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.
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).
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.
Yes. Use the custom_factor field on any activity record to provide your own kg CO2e per unit value. This overrides the database lookup.
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.
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.
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)
# 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/- 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
MIT — free for commercial and personal use.
Built for the GHG Protocol Corporate Standard. 967 emission factors. Zero API costs. One command.