What developer tools does SOMA AI offer to estimate the carbon footprint of AI API calls?

Open-source tools from SOMA AI for engineers. Every figure they return is an estimate.

Page updated

Part of the SOMA AI Emission Factors cluster.

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") from saef.integrations.openai.
  • LiteLLM, with litellm.callbacks = [SaefLogger(region="eu-west-1")].
  • LangChain, with SaefMiddleware(region="eu-west-1") in create_agent(..., middleware=[...]).
  • LlamaIndex, with SaefEventHandler(region="eu-west-1").register(), then .totals().
  • Haystack 2.x, by adding SaefTracker after 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