Ghg Calculator

温室气体排放计算器

开源GHG协议企业标准计算器，内嵌967个排放因子、CLI、MCP服务器和Claude Code技能。

计算从单一天然气账单到整个企业碳清单的所有三个范围的温室气体排放量，而无需付费API、专有数据库或电子表格模板。

   

______________________________________________________________________

这个工具做什么

ghg-calculator 是一个完整的温室气体议定书实施，它：

1. 计算排放量 适用于任何燃料、电力、制冷剂、材料或支出类别
2. 涵盖所有3个范围 --范围1（直接燃烧、逃逸）、范围2（两地购电+市场化）、范围3（全部15个价值链类别）
3. 船舶967排放系数 来自6个免费的同行评审数据库-不需要API密钥
4. 生成交互式HTML报告 使用Plotly图表（范围圆环、瀑布、树状图、趋势线）
5. 作为Claude Code技能工作 --类型 /ghg-analyze 研究和计算任何情景下的排放量

快速开始

# 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

克劳德代码技能： /ghg-analyze

计算任何情况下排放量的最快方法。安装一次，从任何项目使用：

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

然后用自然语言分析任何东西：

/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

该技能会自动执行以下操作：

• 为您的场景研究真实世界的数据（电价、燃料消耗、电网因素）
• 在所有适用范围内建立结构化的活动记录
• 对每种气体分解（CO2、CH4、N2O）进行计算
• 生成带有图表的交互式HTML报告
• 通过上下文比较总结结果（例如，“相当于X辆乘用车”）

______________________________________________________________________

排放因子数据库（967因子）

所有因素都嵌入为版本化的JSON-无需外部API调用，无费率限制，无成本。

参考排放系数

______________________________________________________________________

用例

企业可持续发展团队

计算您组织的年度ESG报告的完整范围1+2+3碳足迹。根据公用事业账单、车队数据和采购支出建立活动记录，然后生成符合GHG协议的报告。

# 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顾问

使用相同的标准化方法为多个客户运行排放分析。嵌入式因子数据库意味着不需要每个客户端API的成本。导出为GHG协议、CDP或GRI 305格式。

气候技术开发商

将MCP服务器或Python API集成到您自己的应用程序中。计算引擎完全可编程：

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代理集成

使用MCP服务器让任何AI代理访问排放计算：

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

可用工具： calculate_emissions, calculate_single, get_emission_factors, list_scopes, list_factor_sources, generate_report, get_gwp_values, convert_units

教育与研究

以透明、开源的方式研究《温室气体议定书》的方法。每次计算都会显示所使用的系数、源数据库和每种气体的细分。

场景建模

比较不同能源组合、地点或运营选择的排放量：

# 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参考

ghg calculate --计算单个活动的排放量

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

选项： --scope, --category, --fuel, --quantity, --unit, --region, --custom-factor, --json

ghg factors --搜索排放系数数据库

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

ghg gwp --查找全球变暖潜势值

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

ghg convert --单位间转换

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

ghg validate --验证JSON活动文件

uv run ghg validate my_activities.json

ghg report --生成交互式HTML报告

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

______________________________________________________________________

活动记录格式

每次计算都从一个活动记录开始——一个描述发生了什么的JSON对象：

范围1：直接排放

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

类别： stationary_combustion, mobile_combustion, fugitive_emissions, process_emissions

燃料类型： natural_gas, diesel, gasoline, propane, jet_fuel, kerosene, coal_bituminous, fuel_oil_2, fuel_oil_6, lpg, ethanol, biodiesel

制冷剂： r-410a, hfc-134a, r-404a, r-407c, r-507a, r-32，以及20+以上

范围2：购电

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

美国eGRID次区域： 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

国际（120个国家）：使用 "country": "GB" 而不是 grid_subregion

作用域2自动生成这两个 基于位置的 和 基于市场的 根据《温室气体议定书》范围2指南得出的结果。

范围3：价值链

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

支持所有15个范围3类别：

1. 采购的商品和服务
2. 资本货物
3. 燃料和能源相关活动
4. 上游运输
5. 运营中产生的废物
6. 商务旅行
7. 员工通勤
8. 上游租赁资产
9. 下游运输
10. 销售产品的加工
11. 销售产品的使用
12. 生命终结治疗
13. 下游租赁资产
14. 专营权
15. 投资

______________________________________________________________________

运作原理

核心配方

CO2e = Activity Data × Emission Factor × Global Warming Potential

对于每个活动，计算器：

1. 匹配排放系数 来自967因子数据库（按燃料类型、地区、类别或NAICS代码）
2. 转换单位 使用品脱（处理热量↔ 千瓦时↔ 英热单位↔ MJ，加仑↔ 升，短吨↔ 吨等）
3. 计算每种气体的排放量 --CO2、CH4和N2O分别计算
4. 应用GWP转换 --每种气体都使用AR5或AR6全球变暖潜势转换为二氧化碳当量
5. 汇总结果 --按范围、类别和气体类型汇总

全球升温潜能值（AR5）

支持AR5和AR6评估报告。AR5是当前GHG协议指南的默认值。

______________________________________________________________________

MCP服务器

MCP服务器将完整的计算器暴露给任何AI代理或MCP兼容客户端：

uv run ghg-mcp

可用工具

MCP配置

添加到您的Claude Code或MCP客户端配置中：

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

______________________________________________________________________

与备选方案的比较

______________________________________________________________________

常见问题

如何计算范围3的排放量？

范围3涵盖了你的价值链——从购买的商品（第1类）到投资（第15类）。最简单的方法是基于支出的：用NAICS代码提供以美元表示的采购支出，计算器使用USEEIO投入产出系数。为了提高准确性，使用基于活动的方法，确定具体数量（钢铁吨数、运输公里数等）和自定义排放系数。

包括哪些排放因子数据库？

六个免费的同行评审数据库：美国环保署排放因子中心（美国燃烧）、eGRID（美国电网）、DEFRA（英国政府运输、材料、废物因子）、USEEIO（美国经济投入产出）、Ember（120个国家的国际电力）和EXIOBASE（欧盟、中国、日本、印度、巴西、俄罗斯的多区域投入产出）。

计算有多准确？

计算器完全遵循GHG协议企业标准方法。准确性取决于您的输入数据质量。使用具有源特定因素的直接活动数据（燃料消耗、仪表读数）进行计算是最准确的。基于支出的范围3估计本质上不太精确，但对筛查很有用。

我可以添加自定义排放系数吗？

对。使用 custom_factor 任何活动记录上的字段，以提供您自己的每单位价值kg CO2e。这将覆盖数据库查找。

支持哪些单位？

能量：千瓦时、兆瓦时、热能、MMBtu、MJ、GJ、CCF、MCF。质量：kg，吨，短吨，磅。体积：加仑，升，桶。距离：公里，英里。货币：美元。基于品脱的转换器自动处理所有标准转换。

双作用域2是如何工作的？

每项电力活动都会自动产生两个结果：基于位置的（使用您所在地区的电网平均值）和基于市场的（使用供应商的特定因素，或者如果没有提供，则使用剩余组合）。这符合《温室气体议定书》范围2指导要求。

______________________________________________________________________

建筑

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/

依赖项

• 派迪克 --数据验证和模型
• 品脱 --单位换算
• 熊猫 --汇总表
• 绘图 --交互式图表
• 打字机+丰富 --CLI界面
• fastmcp --MCP服务器
• jinja2 --HTML报告模板

许可证

麻省理工学院——商业和个人使用免费。

______________________________________________________________________

专为GHG协议企业标准而设计。967排放系数。API成本为零。一个命令。