Short answer
SOMA AI publishes the saef Python package, version 3.5.0 on PyPI, which estimates the carbon, electricity and water of AI API usage from token counts. It has integrations for LiteLLM, LangChain, LlamaIndex and Haystack, an MCP server, and an open dataset of the underlying factors under CC BY 4.0. A free no-code calculator covers the same method.
The saef Python package
The saef package takes input and output tokens, a model and a region, and returns a central estimate, a conservative high case and water. The core has no dependencies. The code is MIT licensed and the data is CC BY 4.0. Source on GitHub.
pip install saef
import saef
usage = {"input_tokens": 1_500_000, "output_tokens": 400_000}
r = saef.estimate(**usage, model="gpt-4o-mini", region="eu-west-1")
print(f"central {r.kg_co2e:.4f} kg CO2e, high case {r.kg_co2e_high_case:.4f} kg CO2e")
print(f"water {r.water_ml:.1f} mL")The guide to tracking emissions from AI API calls shows the printed output and how the package differs from the one-line CSV method.
Framework integrations in saef 3.5.0
Each integration reads the token usage your framework already reports. Install the extra for your stack.
- OpenAI and Anthropic response objects, with
estimate_from_response(resp, region="eu-west-1")fromsaef.integrations.openai. - LiteLLM, with
litellm.callbacks = [SaefLogger(region="eu-west-1")]. - LangChain, with
SaefMiddleware(region="eu-west-1")increate_agent(..., middleware=[...]). - LlamaIndex, with
SaefEventHandler(region="eu-west-1").register(), then.totals(). - Haystack 2.x, by adding
SaefTrackerafter a ChatGenerator and connecting"llm.replies", "saef.replies".
pip install "saef[litellm]" pip install "saef[langchain]" pip install "saef[llamaindex]" pip install "saef[haystack]"
from saef.integrations.llamaindex import SaefEventHandler handler = SaefEventHandler(region="eu-west-1").register() # call your LlamaIndex LLM or query engine as usual print(handler.totals())
MCP server
The same package ships an MCP server so an AI agent can estimate the carbon, energy and water of AI usage on request. It runs locally over stdio in any MCP client, and a hosted copy serves apps that need a remote server. Registry name io.github.guillermollopis/saef, also listed on Glama.
It gives the agent five tools: estimate the footprint of a number of tokens, estimate a number of chat messages, look up a model's size class, list regions, and compare regions. Ask your assistant, for example, "what is the footprint of 2 million GPT-4o tokens in eu-west-1?" or "which region has the lowest footprint for Claude Sonnet?". The commands below use uv, so there is nothing to install first.
Claude Code
claude mcp add saef -- uvx --from "saef[mcp]" saef-mcp
Claude Desktop, Cursor, Windsurf and Gemini CLI
Add this to the MCP settings file: claude_desktop_config.json (Claude Desktop, Settings, Developer), ~/.cursor/mcp.json (Cursor), ~/.codeium/windsurf/mcp_config.json (Windsurf) or ~/.gemini/settings.json (Gemini CLI).
{
"mcpServers": {
"saef": { "command": "uvx", "args": ["--from", "saef[mcp]", "saef-mcp"] }
}
}VS Code (GitHub Copilot agent mode)
In .vscode/mcp.json in your project, or with the command MCP: Add Server.
{
"servers": {
"saef": { "type": "stdio", "command": "uvx", "args": ["--from", "saef[mcp]", "saef-mcp"] }
}
}OpenAI Codex CLI
In ~/.codex/config.toml.
[mcp_servers.saef] command = "uvx" args = ["--from", "saef[mcp]", "saef-mcp"]
ChatGPT, claude.ai and Mistral Le Chat (remote server)
Apps that only accept remote MCP servers can use the hosted version at https://mcp.somaai.earth/mcp. It is read-only, needs no login and returns the same numbers as the package.
- ChatGPT: Settings, Apps and Connectors, Advanced settings, turn on Developer mode, then create a connector with that URL and no authentication.
- claude.ai and Claude Desktop: Settings, Connectors, Add custom connector, then paste the URL.
- Mistral Le Chat: Connectors, Add connector, Custom MCP connector, then paste the URL.
Any other MCP client
Any client that can start a local command over stdio works, for example Cline, Zed or LM Studio. Without uv, install the package and run the command.
pip install "saef[mcp]" saef-mcp
The assistant passes token counts it knows or estimates, so the result is only as exact as those counts. For exact counts from your own API calls, use the package or the framework integrations above.
Open dataset
The SOMA AI Emission Factors (SAEF) are open under CC BY 4.0, versioned, and archived with the concept DOI 10.5281/zenodo.20443585. Take them from GitHub, Hugging Face or as a CSV, and read the factors page. A partner factors API needs a key from SOMA AI.
Method
The method is published in Sustainable Production and Consumption (2026), doi 10.1016/j.spc.2026.11.003. The methodology page sets out the terms, ranges and sources.
No-code option
To estimate without code, use the free SOMA AI calculator.
Short answers
- Is there a Python library to estimate the carbon footprint of LLM API calls?
- Yes. The saef package on PyPI turns input and output token counts, a model and a cloud region into an estimate of kg CO2e, electricity and water, with a high case. Install it with pip install saef. EcoLogits is the other open-source option.
- Is there an MCP server for AI emissions?
- Yes. The saef MCP server lets Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI, Codex CLI and any other MCP client estimate the carbon, energy and water of AI usage on request. Run it with uvx --from "saef[mcp]" saef-mcp, no install needed, or connect ChatGPT, claude.ai or Le Chat to the hosted server at https://mcp.somaai.earth/mcp. It is listed in the MCP registry as io.github.guillermollopis/saef.
- Can I track carbon in a LangChain, LlamaIndex, LiteLLM or Haystack app?
- Yes. saef 3.5.0 has integrations for all four, installed as extras such as saef[langchain]. Each reads the token usage the framework already reports and returns estimates.
- Are the numbers measurements?
- No. Providers do not publish energy per customer, so every figure is an estimate from tokens, model class and the grid, labelled as such, with the factor version recorded.
Keep reading
- How can I track emissions from AI API calls for carbon accounting? Log tokens, apply a factor, total by month
- SOMA AI Emission Factors table and download. The factors by model class and cloud region
- AI and cloud carbon footprint tools compared. Which tool fits what you need to count
