AI Footprint

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

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)

{
  "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?

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:

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

Tools

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

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.

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.

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

git clone https://github.com/nickjlamb/ai-footprint && cd ai-footprint/server
pip install -r requirements.txt
MOCK=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

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

cd server
pip install -r requirements.txt -r requirements-dev.txt
MOCK=1 python -m pytest -q      # tests, including parity with the calculator page
ruff 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 tests
examples/             MCP client, JS and curl examples, captured outputs
web/                  calculator-page embed for the tightener
server.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: info@pharmatools.ai.

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.

<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:

<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