AI Footprint

io.github.nickjlambPublished by GitHub account nickjlambv1.0.4Updated Oct 26, 2026

Water and energy footprint of AI use: chat prompts, agent sessions, methodology and sources.

VerifiedStreamable HTTPWeb executableData & AnalyticsAI & ML

Overview

AI-generated overview

Hosted, read-only MCP server that estimates the water and energy used by AI chat prompts and agent sessions, with methodology and everyday comparisons.

What you can do
  • Estimate energy and water for chat prompts per day or over a period, by usage tier and accounting boundary
  • Estimate the footprint of an agent or coding session from input, output and cached token counts, with a range
  • Convert a water volume into everyday equivalents such as teaspoons, bottles, shower time and lifecycle items
  • Retrieve the per-prompt figures, boundaries, sources, limitations and a citation line, and explain why published estimates differ
When to use it
Useful when you want an assistant to answer questions about the water or energy cost of AI use, check a published figure, or report the footprint of a coding or agent session from its token usage.
Requirements
A remote streamable HTTP endpoint; no install, API key or account. Any MCP client that supports remote servers over streamable HTTP can connect. Self-hosting is optional and needs Python.
Before you install
The figures are indicative estimates built on vendor and non-peer-reviewed sources, not measurements; session results are assumptions and come with a range. The hosted service is read-only and logs only tool names, not inputs or IP addresses, but requests still go to a third-party server.

Installation

In SourceWeft

  1. Open AI Footprint in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.nickjlamb%2Fai-footprint/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "ai-footprint": {
      "type": "http",
      "url": "https://footprint.pharmatools.ai/mcp"
    }
  }
}

README

[AI Footprint: how much water and energy does AI use? Answers with the boundary, assumptions and sources attached.]

[CI] [Release] [MCP Registry] [Hosted endpoint] [Python 3.10 to 3.13] [Methodology 2026-10] [License: MIT]

Quick start · Tools · Examples · Architecture · Methodology · Roadmap · Contributing

AI Footprint is an MCP server and JSON API that estimates the water and energy used by AI: chat prompts, a year of use, or a whole agent session from its token counts. It's the engine behind the PharmaTools.AI AI Water & Energy Calculator, exposed as tools an agent can call.

Published per-prompt estimates of AI water use range from 0.3 mL to 50 mL. Most of that spread is explainable: when the figure was measured, where the accounting boundary is drawn, what kind of workload is counted, and whose data centre it is. So every answer from this server says which boundary it uses, which assumptions it made and which methodology version it comes from. A figure can be checked rather than repeated.

  • Deterministic. No model in any tool. It's arithmetic over a published, versioned methodology: same input, same answer.
  • Zero setup. A hosted, read-only endpoint. No API key, no install, no account.
  • Pinned to its source. The test suite holds the server's outputs identical to the calculator page.

Quick start

Under 60 seconds, from any MCP client. Add the hosted endpoint:

https://footprint.pharmatools.ai/mcp

Claude Code

bash
claude mcp add --transport http ai-footprint https://footprint.pharmatools.ai/mcp

Claude Desktop and claude.ai: Settings → Connectors → Add custom connector, then paste the URL.

Cursor (~/.cursor/mcp.json)

json
{  "mcpServers": {    "ai-footprint": { "url": "https://footprint.pharmatools.ai/mcp" }  }}

Anything else: any client that supports remote MCP servers over streamable HTTP. Point it at the URL above.

Then ask:

How much water do 30 ChatGPT prompts a day use over a working year?

text
estimate_ai_footprint(queries_per_day=30, days=250)
→ 2.6 kWh and 10.5 L over 250 days (comprehensive boundary)  per prompt: 0.34 Wh, 1.39 mL · about 25.5 hrs of TV or 170 phone charges  methodology 2026-10 · source: pharmatools.ai/water-consumption-calculator

Not using MCP? The same tools are plain GET endpoints:

bash
curl "https://footprint.pharmatools.ai/api/footprint?queries_per_day=30&days=250"

Tools

ToolAsk itReturns
estimate_ai_footprint"30 prompts a day for a year"Energy and water per prompt, per day and in total, with everyday equivalents and assumptions. Usage tier simple (~0.34 Wh), mixed (~1 Wh) or intensive (~3 Wh); boundary onsite or comprehensive.
estimate_session_footprint"200k input, 3M cached, 40k output tokens"A central estimate and a 0.3–3× range for an agent or coding session, plus how many typical chat prompts it equals.
compare_water_use"Is 500 mL a lot?"Teaspoons, bottles and shower time, plus lifecycle items (A4 sheet, almond, tea, burger) with the caveat that those use a much wider boundary.
get_methodology"Why do estimates vary so much?"Per-prompt figures, both boundaries, sources, limitations, a citation line, and four reasons published estimates differ by ~100×.

All four are annotated read-only, idempotent and closed-world, so clients can tell they're safe to call. More in examples/: a Python MCP client, a dependency-free JavaScript client, curl for every endpoint and full captured responses.

Architecture

mermaid
flowchart LR    A["MCP clients<br/>Claude · Cursor · agents"] -->|/mcp| R    B["Scripts and browsers"] -->|/api/*| R    C["Calculator page<br/>pharmatools.ai"] -->|/tighten · /read-claim| R
    subgraph app["One ASGI app · server/main.py"]        R{{"Path router<br/>CORS · rate limits"}}        R -->|"open CORS · 120/min"| M["MCP tools<br/>FastMCP, streamable HTTP"]        R -->|"open CORS · 120/min"| J["JSON API<br/>FastAPI GET routes"]        R -->|"pharmatools.ai only · daily caps"| T["Prompt tightener"]        M --> F[("footprint.py<br/>constants · sources · arithmetic")]        J --> F    end
    T --> H["Claude Haiku"]
  • One source of truth. server/footprint.py holds every constant, source and calculation. The MCP tools and the JSON API are thin wrappers, so they can't drift apart, and the tests hold both to the calculator page's figures.
  • Two security postures in one app. The footprint routes are public arithmetic: open CORS, 120 requests per minute per client. /tighten spends API credit, so it accepts the calculator page only, behind per-IP and global daily caps. A small ASGI wrapper picks the right policy by path.
  • Stateless. No database and no sessions. The MCP server runs in stateless JSON-response mode, so any instance can answer any request. Rate limits are in memory, which assumes a single instance (see the roadmap).
  • Private by default. Logs record tool or endpoint names only. Inputs, prompts and IP addresses are not logged.

Methodology

Energy first, water derived from it.

FigureBasis
Energy, simple text prompt~0.34 WhOpenAI's per-query figure; Google reports a median Gemini text prompt at 0.24 Wh (2025)
Energy, image or long reasoning~3 Wh or moreMIT Technology Review analysis (2025)
Water, onsite boundary~1.0 mL/WhData-centre cooling only, as implied by Google's disclosure. The highest of the published provider figures is used.
Water, comprehensive boundary~4.1 mL/WhAdds ~3.1 mL/Wh consumed generating the electricity (US grid average, Li et al.)
Typical text prompt~0.34 mL onsite, ~1.4 mL comprehensiveThe widely quoted 2023 estimates describe hardware that no longer exists

Session estimates are calibrated so ~1,000 input + ~400 output tokens on a frontier model equals one typical prompt (0.34 Wh), with output tokens costing ~5× input and cache reads ~0.1×. These are assumptions, not measurements, so the tool returns a range and says so.

Limitations. Vendor figures aren't peer-reviewed, describe median prompts and exclude training. Electricity-generation water uses US grid averages. Results are indicative estimates.

Sources. Google (2025) · OpenAI per-query figures · Li et al., Making AI Less Thirsty · MIT Technology Review (2025) · Water Footprint Network

The full write-up is on the calculator page. When the methodology changes, METHODOLOGY_VERSION is bumped and the change is recorded in the changelog. Found a better source? Open a methodology issue.

JSON API

The same four tools as GET endpoints with open CORS. GET /api lists them.

EndpointParameters
/api/footprintqueries_per_day (required), usage=simple|mixed|intensive, boundary=onsite|comprehensive, days
/api/sessioninput_tokens, output_tokens (required), cached_input_tokens, model_class=small|frontier|reasoning, boundary
/api/comparewater_ml (required)
/api/methodologynone

Invalid input returns 400 with a message saying what's allowed. Responses are cacheable for an hour. The limit is 120 requests per minute per client.

Self-hosting

bash
git clone https://github.com/nickjlamb/ai-footprint && cd ai-footprint/serverpip install -r requirements.txtMOCK=1 uvicorn main:app --port 8000# MCP at http://localhost:8000/mcp · JSON API at http://localhost:8000/api

MOCK=1 makes the tightener return a canned rewrite, so no Anthropic key is needed. The footprint tools don't use a key either way. The included Procfile runs as is on Railway, Render, Heroku and similar platforms.

Configuration
VariableDefaultPurpose
ANTHROPIC_API_KEYnoneRequired for /tighten unless MOCK=1
MOCKunset1 returns a canned tightener response
MODELclaude-haiku-4-5Model for the tightener
ALLOWED_ORIGINShttps://www.pharmatools.ai,https://pharmatools.aiCORS allowlist for /tighten
PER_IP_PER_MIN / PER_IP_PER_DAY4 / 25Tightener per-client limits
GLOBAL_PER_DAY1500Tightener daily cap across all clients
MAX_INPUT_CHARS1500Tightener input cap
PUBLIC_PER_IP_PER_MIN120Limit for /mcp and /api/*
DOCS_URLhttps://www.pharmatools.ai/mcp#footprintWhere / redirects
PROXY_ENTRIES1How many entries your hosting proxy adds to the right of X-Forwarded-For (Railway: 1). Rate limits use the entry just before them; anything further left is ignored

Also in this repo: the prompt tightener

POST /tighten powers the "Make your first prompt the only one" tool on the calculator page. It sends a draft prompt to Claude Haiku, which rewrites it to get a usable answer first time, filling gaps with [placeholders] rather than invented facts. The page then shows what the rewrite itself cost in water against the follow-ups it should save. Unlike the footprint tools it calls a model, so it's locked down: pharmatools.ai-only CORS, a 1,500-character input cap, per-IP and daily caps, forced tool output and no prompt logging. The page embed is in web/prompt-tightener-embed.html.

POST /read-claim backs the headline checker on the same page. The page reads well-known claims and simple figures itself, in the browser. Only when it can't, and the visitor chooses to, it sends the claim here. The model just extracts what the claim states (amount, unit, what it's per), and the page explains it with fixed rules. It has the same protections as /tighten.

Development

bash
cd serverpip install -r requirements.txt -r requirements-dev.txtMOCK=1 python -m pytest -q      # tests, including parity with the calculator pageruff check ..                   # lint

CI runs lint and tests on Python 3.10 to 3.13, then starts the server and drives it end to end with the MCP client example. Pushing a v* tag publishes a GitHub release with notes taken from the changelog.

server/  footprint.py        constants, methodology and arithmetic (single source of truth)  mcp_tools.py        the four MCP tools  main.py             ASGI app: /mcp, /api/*, /tighten, /read-claim, CORS and rate limits  test_footprint.py   parity, validation and HTTP testsexamples/             MCP client, JS and curl examples, captured outputsweb/                  calculator-page embed for the tightenerserver.json           MCP Registry entry

Privacy

The hosted server keeps no record of what you ask. Its logs contain the name of the tool or endpoint called, nothing else: no inputs, prompts or IP addresses. Client IP addresses are held in memory only to enforce rate limits. They are never logged or written to disk, and are discarded when the server restarts. There's no database and no account. The server runs on Railway, and nothing is shared with anyone else. Full policy: pharmatools.ai/privacy-policy. Questions: [email protected].

Contributing

Issues and pull requests are welcome, particularly better sources. Read CONTRIBUTING.md first: changes to the figures follow a short methodology process so the server and the calculator page stay in step. Security issues go through SECURITY.md, not public issues.

Embed the calculator on your site

One line, no account or key. It works on any site that accepts a script tag, including WordPress, Webflow, Squarespace and Ghost.

html
<script src="https://footprint.pharmatools.ai/widget.js" data-theme="auto" data-prompts="25" data-mix="text" async></script>

Options: data-theme (light, dark, auto), data-accent (a hex colour such as 0d7377), data-prompts (1–200), data-mix (text, mixed, intensive) and data-basis (comprehensive, onsite). Where scripts aren't allowed, use the iframe directly:

html
<iframe src="https://footprint.pharmatools.ai/widget?theme=auto&prompts=25" title="AI water and energy calculator" width="100%" height="560" style="border:0;max-width:640px" loading="lazy"></iframe>

The widget uses the same figures and methodology version as the API, computes everything in the visitor's browser and sets no cookies. The calculator page has a builder with a live preview.

Citing

Lamb, N. (2026). An energy-first method for estimating the water and energy footprint of AI use (methodology 2026-10) [Preprint]. Zenodo. https://doi.org/10.5281/zenodo.23417340

GitHub's Cite this repository button gives the software citation from CITATION.cff.

License

MIT © PharmaTools.AI

Source: README.md at commit 22449b1

Tools

4

estimate_ai_footprint

Estimate AI water & energy footprint

Estimate the water (mL) and energy (Wh) used by chat-style AI prompts (ChatGPT, Claude, Gemini etc.). queries_per_day: prompts per day. usage: 'simple' (text chat, ~0.34 Wh/prompt), 'mixed' (~1 Wh), 'intensive' (image generation / deep reasoning, ~3 Wh). boundary: 'onsite' (data-centre cooling only, as vendors report) or 'comprehensive' (adds water used to generate the electricity – the wider boundary most researchers use). days: number of days to total over (e.g. 250 workdays, 365). Returns per-prompt, per-day and total figures with everyday equivalents, assumptions and a source link. For agentic/coding sessions use estimate_session_footprint instead.

Parametersdaysusageboundaryqueries_per_dayrequired

get_methodology

AI water footprint methodology and sources

Return the per-prompt energy and water figures, accounting boundaries, sources, limitations, a citation line, and the reasons published AI water estimates differ by ~100x (0.3 mL to 50 mL per prompt). Use it to explain or check a published AI water or energy figure.

Takes no parameters.

compare_water_use

Put an amount of water in everyday context

Convert a volume of water (mL) into everyday comparisons: teaspoons, 500 mL bottles, shower time, and lifecycle items (A4 sheet, almond, cup of tea, beef burger), plus the number of typical AI text prompts it equals. Includes the boundary caveat that lifecycle footprints are not like-for-like.

Parameterswater_mlrequired

estimate_session_footprint

Estimate an AI session's footprint from token counts

Estimate the water and energy of an AI session (e.g. an agent or coding-assistant run) from its token usage. Pass the SUM across all model calls: input_tokens (uncached prompt tokens), output_tokens (including any reasoning/thinking tokens) and cached_input_tokens (prompt-cache reads). model_class: 'small' (Haiku/mini/Flash-class), 'frontier' or 'reasoning'. Returns a central estimate and a 0.3x–3x range – this is an order-of-magnitude estimate calibrated to published per-prompt figures, not a measurement.

Parametersboundarymodel_classinput_tokensrequiredoutput_tokensrequiredcached_input_tokens

Version history

3
  1. v1.0.4LatestOct 13, 2026
  2. v1.0.3Oct 13, 2026
  3. v1.0.0Oct 11, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts