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 Claude · Cursor · agents"] -->|/mcp| R B["Scripts and browsers"] -->|/api/*| R C["Calculator page pharmatools.ai"] -->|/tighten · /read-claim| R

subgraph app["One ASGI app · server/main.py"] R{{"Path router CORS · rate limits"}} R -->|"open CORS · 120/min"| M["MCP tools FastMCP, streamable HTTP"] R -->|"open CORS · 120/min"| J["JSON API FastAPI GET routes"] R -->|"pharmatools.ai only · daily caps"| T["Prompt tightener"] M --> F[("footprint.py 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 extr