Metadata-Version: 2.4
Name: carbon-footprint-mcp
Version: 1.0.0
Summary: An MCP server for calculating carbon footprints from bank statements and activity data using EPA GHG emission factors.
Project-URL: Homepage, https://github.com/MayankTalwar0/carbon-footprint-mcp
Project-URL: Repository, https://github.com/MayankTalwar0/carbon-footprint-mcp
Project-URL: Issues, https://github.com/MayankTalwar0/carbon-footprint-mcp/issues
Project-URL: Changelog, https://github.com/MayankTalwar0/carbon-footprint-mcp/blob/main/CHANGELOG.md
Author: Mayank
License: MIT License
        
        Copyright (c) 2026 Mayank Talwar
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: carbon,emissions,esg,ghg,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp>=1.1.1
Description-Content-Type: text/markdown

# Carbon Footprint Calculator (MCP Server)

An MCP (Model Context Protocol) server for calculating organizational carbon footprints from bank statements, financial exports, and structured activity data using EPA GHG emission factors.

> **Privacy and security first**
> - Runs 100% locally on your machine or server
> - Sends no financial data to external APIs or cloud providers
> - Stores no data by default
> - Exposes read-only calculation and reporting tools
> - Works with Claude Desktop, Cursor, and other MCP clients

<!-- mcp-name: io.github.MayankTalwar0/carbon-footprint-mcp -->

## Why This Exists

If you are preparing ESG reporting, investor diligence materials, or internal sustainability reviews, getting to a usable emissions baseline is usually slow and manual.

This server helps turn raw bank statements, Xero or QBO exports, and structured operational inputs into a carbon footprint report in minutes. It maps activities to EPA-aligned emission factors and produces both HTML and Markdown outputs.

The user experience is designed to work for organizations in any country, while the current electricity benchmarking still uses EPA eGRID regional factors under the hood.

## What It Does

1. Ingests bank CSVs, Xero or QBO exports, and structured activity data.
2. Helps categorize transactions into likely emission sources such as electricity, fuel, travel, shipping, and waste.
3. Computes Scope 1, Scope 2, and Scope 3 emissions using EPA GHG emission factors.
4. Scores carbon intensity by revenue and headcount when those inputs are provided.
5. Generates polished HTML and Markdown reports.

## Emission Factor Source

All emission factors are based on the EPA GHG Emission Factors Hub (January 2025), including eGRID 2023 electricity factors and IPCC AR5 global warming potentials.

Covered categories include stationary combustion, mobile combustion, electricity, steam or heat, transportation, waste disposal, business travel, employee commuting, and refrigerants.

## Installation

### Claude Desktop

1. Install `uv`.
2. Open Claude Desktop settings and edit the MCP config.
3. Add this server:

```json
{
  "mcpServers": {
    "carbon-footprint": {
      "command": "uvx",
      "args": ["carbon-footprint-mcp"]
    }
  }
}
```

4. Restart Claude Desktop.

### Claude Code or Cursor

```bash
claude mcp add carbon-footprint -- uvx carbon-footprint-mcp
```

### Local Development

```bash
git clone https://github.com/MayankTalwar0/carbon-footprint-mcp.git
cd carbon-footprint-mcp
pip install -e .
carbon-footprint-mcp
```

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `computeEmissions(inputs_json)` | Computes GHG emissions from structured activity data across all 3 scopes. |
| `generateEmissionsReport(emissions_json, output_dir)` | Renders a polished HTML and Markdown report and saves it to disk. |
| `listEmissionFactors(category)` | Lists available fuel, eGRID, and waste emission factors. |

## Supported Emission Categories

| Scope | Category | Input Required |
|-------|----------|----------------|
| 1 | Stationary Combustion | Fuel type and quantity |
| 1 | Mobile Combustion | Fuel type and gallons |
| 1 | Refrigerant Leakage | Gas type, leaked kg, and GWP |
| 2 | Purchased Electricity | kWh and eGRID subregion |
| 2 | Purchased Steam or Heat | mmBtu |
| 3 | Transportation and Distribution | Vehicle type and distance |
| 3 | Waste Disposal | Material, short tons, and disposal method |
| 3 | Business Travel | Travel mode and passenger-miles |
| 3 | Employee Commuting | Commute mode and passenger-miles |

## Carbon Intensity Scoring

| Score | tCO2e per $1M Revenue | Interpretation |
|-------|-----------------------|----------------|
| Excellent | < 5 | Best-in-class for low-footprint operations |
| Good | 5-20 | Low intensity |
| Moderate | 20-100 | Typical for services and tech |
| High | 100-500 | Heavy operations |
| Very High | > 500 | Very high intensity |

## License

MIT

## Built By SlickBooks

Built by Mayank, founder of [SlickBooks](https://slickbooks.online).
