使用说明

温室气体排放计算器

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

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

这个工具做什么

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

计算排放量 适用于任何燃料、电力、制冷剂、材料或支出类别
涵盖所有3个范围 --范围1（直接燃烧、逃逸）、范围2（两地购电+市场化）、范围3（全部15个价值链类别）
船舶967排放系数 来自6个免费的同行评审数据库-不需要API密钥
生成交互式HTML报告 使用Plotly图表（范围圆环、瀑布、树状图、趋势线）
作为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调用，无费率限制，无成本。

来源	因素	覆盖范围	用例
EPA中心	113	美国固定/移动燃烧、制冷剂	范围1：天然气、柴油、汽油、丙烷、喷气燃料
eGRID	122	美国电网（27个子区域）	范围2：按地区划分的美国电力（ERCT、CAMX、RFCE等）
环境、食品及农村事务部	117	英国/国际运输、材料、废物	范围1/3：车辆、航班、航运、建筑材料
USEEIO 公司	264	美国按北美产业分类体系部门划分的支出	范围3：通过经济投入产出购买的商品/服务
余烬	120	国际电力（120个国家）	范围2：按国家划分的全球电力（GB、DE、CN、JP等）
EXIOBASE	231	多区域投入产出（欧盟、中国、日本、印度、巴西、俄罗斯）	范围3：基于国际支出的估算

参考排放系数

活动	因素	来源
天然气	5.3千克二氧化碳当量/热量	美国环保署中心
柴油	10.21千克二氧化碳/加仑	美国环保署中心
汽油	8.78千克二氧化碳/加仑	EPA Hub
美国电网平均值	0.37千克二氧化碳/千瓦时	eGRID
ERCOT（德克萨斯州）	0.37千克二氧化碳/千瓦时	eGRID
CAMX（加利福尼亚州）	0.24千克二氧化碳/千瓦时	eGRID
英国电网	0.21千克二氧化碳/千瓦时	Ember
德国电网	0.35千克二氧化碳/千瓦时	Ember

用例

企业可持续发展团队

计算您组织的年度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类别：

采购的商品和服务
资本货物
燃料和能源相关活动
上游运输
运营中产生的废物
商务旅行
员工通勤
上游租赁资产
下游运输
销售产品的加工
销售产品的使用
生命终结治疗
下游租赁资产
专营权
投资

运作原理

核心配方

CO2e = Activity Data × Emission Factor × Global Warming Potential

对于每个活动，计算器：

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

全球升温潜能值（AR5）

天然气	GWP（100年）
二氧化碳	1
第4章	28
2年	265
HFC-134a	1300
R-410A	2088
SF6	23500

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

MCP服务器

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

uv run ghg-mcp

可用工具

工具	说明
`calculate_emissions`	计算多种活动的排放量
`calculate_single`	计算一项活动的排放量
`get_emission_factors`	搜索和检索排放系数
`list_scopes`	列出可用范围和类别
`list_factor_sources`	列出所有因素数据库及其覆盖范围
`generate_report`	根据活动数据生成HTML报告
`get_gwp_values`	查找任何温室气体的全球变暖潜值
`convert_units`	在能量、质量和体积单位之间转换

MCP配置

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

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

与备选方案的比较

功能	ghg-calculator	Climatiq API	电子表格	Persefoni/Sweep
价格	免费 (MIT)	$0.01/calc	免费	$50K+/年
排放系数	967嵌入式	40000+（API）	手动输入	专有
离线功能	是	否	是	否
需要API密钥	否	是	不适用	是
全部3个范围	是	是	手动	是
双作用域2	自动	手动	手动	是
每次气体分解	是	一些	否	是
AI代理集成	MCP+技能	REST API	否	否
开源	是	否	不适用	否
交互式报告	Plotly HTML	否	图表	仪表板

常见问题

如何计算范围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成本为零。一个命令。